Files
mtusi2026lab4/openspec/changes/attachments/tasks.md
T
ricoromaandClaude Opus 5.5 116d8d3bf0 feat: add image attachments to messages
- upload, metadata and download endpoints for PNG/JPEG attachments:
  limits before reading and decompression, type by content,
  structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
  per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
  whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
  CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
  rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 01:08:56 +03:00

350 lines
23 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.
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
`api-contract.md`, `api-layer.md`, `auth.md` (`dependencies.py`,
`errors.py`), `service-layer.md`, `repo-layer.md`, `dto.md`,
`migrations.md`, `logging.md`, `settings.md`, `student-tests.md`,
`bench.md`, `balancer.md` (драйвер и `stop-one.sh`). Evidence снимается с
закоммиченного кода, коммит — только после подтверждения пользователя
(`bench.md`, «Измеренное состояние — commit»).
Ответы пользователя 2026-10-20 (`PLAN.md`, `### attachments` →
«Вопросы»):
- п. 1 — структурная проверка изображения;
- п. 2 — ответ преподавателя 2026-10-20 (AGENTS.md, «Согласования с
преподавателем»; design, решение 8): «пустой текст» — и `""`, и текст
из одних пробелов; с хотя бы одним вложением он допустим (201, текст
как прислан), без вложений — 400. Валидатор `CreateMessage`,
сценарий `messages` «Пробелы с вложением» и его тест — под это;
- п. 3 — `filename` отклоняется только по списку контракта: `/`, `\` и
управляющие символы категории Cc, остальное принимается.
Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md:
- до задачи 5.5 (sync дельт) тесты с маркерами новых сценариев падают на
сверке: «marker points to unknown scenario»;
- до задачи 9.2 `test_exclusion_evidence_exists`: нет файлов исключений.
Это четыре файла перехода из AGENTS.md («Переход в следующую лабу»)
и `evidence/attachments/failover.md`, `storage.md`.
## 1. Основа: константы, enum, DTO, исключения, проверка изображения
- [x] 1.1 Типы домена по решениям 2, 4 и 10:
- константы в `src/utils/constants.py`: лимиты, длины `filename`,
запрещённые символы `filename` (`/`, `\`, категория Cc),
`MESSAGE_ATTACHMENTS_MAX`, префикс и суффикс ключа объекта;
- `src/schemas/enums/attachment.py` (`AttachmentStatus`,
`ImageType`);
- `src/schemas/dataclasses/attachment.py` (`AttachmentFullDTO`,
`AttachmentContentDTO`), поле `attachment_ids: tuple[UUID, ...] =
()` в `MessageFullDTO`;
- `src/core/exceptions/attachment.py` (`AttachmentNotFound`,
`PayloadTooLarge`, `UnsupportedMediaType`, `UploadInterrupted`,
`AttachmentContentMissing`);
- реэкспорт в `__init__.py` пакетов по алфавиту.
Проверка: `make lint`; `uv run python -c "from src.core import
exceptions; from src.schemas import dataclasses, enums; print(…)"`
без ошибок.
- [x] 1.2 `src/utils/image.py` по решению 2: `inspect_image(data, *,
max_pixels)` → `ImageInfo` (тип, ширина, высота), исключения
`UnsupportedImage`, `DamagedImage`, `TooManyPixels`. Только stdlib;
фильтры строк — срезом с шагом строки, конец скана JPEG — регулярным
выражением. Проверка — разовый скрипт в scratchpad (`uv run
--no-project --with pillow python -I`), который импортирует модуль по
пути. Повторить пробу из design, Context:
- 17 вариантов приняты;
- повреждённые из списка — `DamagedImage`, хвосты приняты;
- подмена размеров SOF — `TooManyPixels`;
- «бомба» 100 × 100 / 200 MiB — `DamagedImage` быстрее 10 мс;
- PNG 1 × 40 млн и 40 млн RGBA — не дольше 0,5 с, пик `tracemalloc`
до 5 MiB;
- корпус из 12 000 случайных PNG и JPEG системы: ни одного файла,
который загружает Pillow, а модуль отклоняет, кроме лимита пикселей.
Итоги — строкой в design, «Уточнения apply».
## 2. Схема БД
- [x] 2.1 Модели по решению 3: `src/infra/db/models/attachment.py`
(`Attachment`, `MessageAttachment` с ограничениями и индексом по
`attachment_id`), новое условие `text_length` в `Message`, экспорт в
`models/__init__.py`. Проверка: `make revision` даёт ревизию с двумя
таблицами и индексом. Ослабление CHECK autogenerate не видит
(`migrations.md`).
- [x] 2.2 Ревизия руками по решению 3:
- первая строка `SET LOCAL lock_timeout = '2s'`;
- CHECK литералами, а не константами `src`;
- `DROP CONSTRAINT ck_messages_text_length` и `ADD CONSTRAINT … CHECK
(char_length(text) <= 4000) NOT VALID`;
- `downgrade` зеркально, строгое ограничение тоже `NOT VALID`.
Проверка:
- `uv run alembic upgrade head --sql` содержит `NOT VALID`;
- `make upgrade` на рабочей базе, повторный `upgrade head` — без
изменений;
- на временной базе (`createdb` в контейнере `postgres`, `DATABASE__NAME`
в окружении): `upgrade` с нуля → `downgrade -1` → `upgrade`, затем
`DROP DATABASE`;
- psql в транзакции с откатом:
- строка с каждым нарушением CHECK отклонена: размер, SHA-256, тип,
статус, `filename` с `/`, `\`, U+0001, U+007F, U+0085 и из 256
символов;
- допустимая строка принята, в том числе с `filename`, где есть
U+202E, U+2028 и U+00AD: CHECK не строже API;
- владелец не участник — отказ FK;
- удаление вложения со связью — отказ FK;
- повтор вложения в сообщении и позиция 10 — отказ;
- `\d attachments`, `\d message_attachments` — по таблице решения 3.
## 3. Repo и сервисы
- [x] 3.1 Repo по решениям 3, 4 и 8:
- `src/core/repos/attachment.py`: `insert_attachment`, `mark_ready`
(`UPDATE … WHERE status = 'pending' RETURNING`), `get_attachment`,
`get_attachments`;
- `src/core/repos/attachment_object.py`: `original_key`,
`put_original`, `open_original` поверх `ObjectStorage`;
- `src/core/repos/message.py`: `MESSAGE_COLUMNS` с подзапросом
`ARRAY(...)`, вставка сообщения явными колонками,
`insert_message_attachments` одной вставкой.
В каждой функции одно выражение. Проверка: `make lint`. Поведение —
через HTTP в группах 4–5; план истории — задача 7.2.
- [x] 3.2 `src/core/services/attachment.py` — `AttachmentService(db_scope,
cache, storage)` по решениям 1, 5, 6, 7, 11: `upload`,
`get_attachment`, `open_content`. Проверка, загрузка, SHA-256 и
размеры — одним `anyio.to_thread.run_sync`. Каждый шаг с БД — свой
`async with self.db_scope()`, без вложенных. Журнал без `filename`.
Проверка: `make lint`, дальше задача 4.3.
- [x] 3.3 `MessageService.send_message(..., attachment_ids)` по решениям
8 и 9:
- проверка вложений до захвата ключа;
- связи после вставки сообщения, один commit;
- `message_request_hash(text, attachment_ids)`: пустой список хэш не
меняет, id — `str(UUID)`;
- `attachments_count` в записи журнала.
Проверка: разовый вызов `message_request_hash` — хэш `{"text": "x"}`
равен хэшу версии `e1161f7` (`git show e1161f7:src/core/services/
message.py`), список в верхнем и нижнем регистре даёт один хэш,
другой порядок — другой.
## 4. Слой API
- [x] 4.1 `src/api/dependencies.py` по решению 5:
- `db_session_scope()`;
- `get_db_session` — обёртка над ним;
- `get_current_user_brief` и `CurrentUserBrief`;
- `get_attachment_service` и `AttachmentServiceDep` (глобал
`object_storage`).
`src/api/errors.py` — строки таблицы решения 10. Проверка: `make lint`;
`make student_test` через LB — те же итоги, что до правки (красное —
только схема `Message`, сверка и исключения). JSON-ручки не изменились.
- [x] 4.2 Схемы и ручки по решениям 6, 7, 8, 10:
- `src/api/schemas/attachment.py`: `DisplayFilename` (отказ на `/`,
`\`, символы категории Cc и строку из одних пробелов, решение 10),
`Attachment`;
- `src/api/schemas/message.py`: `CreateMessage` с `attachment_ids` и
валидатором, `Message` с `attachment_ids`;
- `src/api/routers/v1/attachment.py`: загрузка с `openapi_extra`,
метаданные, `content` со `StreamingResponse`, обёртка над
`request.stream()` с `UploadInterrupted`;
- подключение в `routers/v1/__init__.py`, параметр `attachment_ids` в
ручке сообщения.
Проверка: `/openapi.json` запущенного сервера содержит три пути
контракта, тело загрузки `image/png` / `image/jpeg` и параметр
`variant` с перечислением `original`.
- [x] 4.3 Проверка на живом сервере. Консоль — `driver.py start`, стенд
— `make rolling_update`: одна миграция, затем замена по одной.
- `make test` против обоих: `PASS: lab4 public API scenario`.
- Руками через `driver.py req` и curl:
- 413 по `Content-Length` и частями;
- 415 на текст и подмену MIME;
- 400 на `filename` с `/` и с U+0085, 201 на `filename` с U+202E —
имя в ответе то же;
- 404 постороннему на загрузку, метаданные и байты;
- 503 на загрузку и скачивание при `make stop_s3`, метаданные 200;
- после `make start_s3` — 201 и 200;
- журнал (`make logs` без `-f`) не содержит переданных `filename`.
- Разовый скрипт в scratchpad (решение 5): загрузка 10 MiB частями за
~12 с и скачивание 10 MiB с чтением за ~12 с через LB — 201 и 200
без «Database is unavailable» в журнале.
## 5. Тесты
- [x] 5.1 `uv add --dev pillow`. `student-tests/images.py` — генераторы
по решению 12. Проверка:
- `uv lock --check`;
- `docker run --rm mtusi-messenger:lab4 python -c "import PIL"`
завершается ошибкой: в образе Pillow нет;
- `uv run python -c` с импортом `images` даёт PNG ровно 10 485 760
байт, и `inspect_image` его принимает.
- [x] 5.2 `student-tests/api_client.py` и `contract.py` по решению 12:
- загрузка, метаданные, байты, `send_message(..., attachment_ids)`;
- коды 413 и 415, `owner_id`, элементы `attachment_ids`,
`updated_at`;
- `assert_content`.
Проверка: прежние тесты проходят на коде группы 4.
- [x] 5.3 `student-tests/test_attachments.py` — сценарии спека
`attachments`, кроме проверок отказов и исключений, с маркерами
`spec`. В «Опасном имени» — только символы контракта, в «Символах
форматирования в имени» — 201 и то же имя в ответе и метаданных.
«Скачивание через другую реплику» — с фикстурой `replicas`. В
`test_rubric.py` — пять сценариев рубрики «4» лабы 4. Новые сценарии
дельт `messages`, `idempotency`, `api-conventions`, `data-storage` — в
их модулях. Проверка: `make student_test` через LB и `make
test_isolated` — новые тесты проходят; на рабочем стенде через LB
`replicas`-тест выполняется, в `test_isolated` пропущен с причиной.
- [x] 5.4 Проверки отказов по дельте `student-tests`:
- `test_failures.py`: «Запись в S3 не удалась», «Отклонённая загрузка
ничего не оставляет», «S3 остановлен», «S3 завис» в `with
outage(...)`;
- `fault_hook.py`: действия `count-attachments` и `count-objects`,
docstring;
- `run_failures.py`: bucket и имя базы в окружении hook.
Проверка: `make failure_checks FAULT_ARGS='-k attachment or
object_storage'`, затем полный `make failure_checks` — код 0, стенд
отказов удалён, у рабочего стенда прежний `StartedAt`.
- [x] 5.5 Сверка покрытия:
- `attachments` в `CAPABILITIES` (`spec_coverage.py`);
- исключения «Принявшая реплика остановлена», «Байты не в БД и не на
диске API», «Рестарт стенда» с причиной и командой по решению 12;
- синхронизация всех дельт change в основные спеки (`/opsx:sync`),
как `health` в `s3-storage`.
Проверка: `make student_test` — сверка без «no test and no
exclusion» и «unknown scenario». Красное — только
`test_exclusion_evidence_exists` по списку в шапке.
## 6. Драйвер скилла `run-mtusi-messenger`
- [x] 6.1 Команды `upload` и `download` по решению 13. Проверка против
`driver.py start` и стенда (`--port 8080`): загрузка
`tests/fixtures/sample.png`, скачивание вторым участником — SHA-256
`99ea7533…` совпадает; 404 постороннему; `ruff format --check` и
`make lint` проходят.
- [x] 6.2 `attachment-failover [--mode stop|kill]` по решению 13.
Проверка на стенде: оба режима — код 0, скачивание от реплики с
другим `X-Instance-Id`, SHA-256 совпал, после команды снова
`API_REPLICAS` реплик `UP` (`make lb_stats`). Отрицательная проверка:
без балансировщика (`--port` консольного процесса) — код 2 и
понятное сообщение.
- [x] 6.3 `attachment-storage` по решению 13. Проверка:
- на стенде код 0;
- отрицательная: `s3.anonymous.set -access Read` через `docker compose
exec s3 weed shell` — код 1 с названной проверкой; `docker compose up
-d s3-bootstrap` закрывает доступ, и снова код 0.
- [x] 6.4 `flow` с вложением по решению 13, раздел о вложениях в
`SKILL.md`: команды, gotchas — `urllib` напрямую к реплике и ранний
413; S3 нужен только путям вложений. Проверка: `driver.py all` — код
0, `FAILED: none`.
## 7. Стенд `bench/`
- [x] 7.1 `rollout_from = "e1161f7"` в профилях `rollout` и
`rollout_quick` (комментарий профиля — тоже) и проверка commit до
стенда по решению 14 и дельте `load-benchmark`. Правило в `bench.md`,
удаление записи из `KNOWN_ISSUES.md`. Проверка:
- `uv run python bench/run.py --profile rollout_quick --from 0000000`
— ненулевой код до запуска стенда, в сообщении commit и `--from`;
- `make bench_rollout_quick` — код 0, в `meta.json` метки
`from_commit` `e1161f7`;
- ревизия до замены — `e656d6bbe1a4`, после — новая.
- [ ] 7.2 Регресс прежних профилей: `make bench_quick`, `make
bench_failover_quick`, `make bench_restore_quick` — код 0. В
`explain-10k.txt` пробной метки узел истории — прежний индекс
`messages`, а `SubPlan` идёт по `pk_message_attachments` (решение 8).
Пробные метки `quick-*` в git не идут.
## 8. Документы и проверка кода
- [x] 8.1 Правила:
- `api-contract.md` — раздел лабы 4: ручки, коды 413 и 415 в
таблице, порядок проверок загрузки, `filename` (только символы
контракта, категория Cc), `UuidIn` для id вложений, ранний ответ и
`urllib`, пустой текст (в том числе из пробелов) с вложением —
201 по согласованию с преподавателем;
- `api-layer.md` — роутер с двумя префиксами, `CurrentUserBrief`,
тело без параметра, `StreamingResponse`, `UploadInterrupted`;
- `service-layer.md` — `AttachmentService` с `db_scope`, порядок
записи, проверка вложений сообщения, хэш;
- `repo-layer.md` — repo вложений, repo объекта S3, подзапрос
`ARRAY`;
- `dto.md` — новые DTO и enum;
- `migrations.md` — таблицы вложений, ослабление CHECK `NOT VALID`,
почему не `autocommit_block`;
- `logging.md` — записи `attachment_service`, `filename` не пишется;
- `student-tests.md` — `test_attachments.py`, `images.py`, Pillow в
dev, отказы S3 и действия hook, новые исключения;
- `settings.md` — `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` —
константы;
- `bench.md` — `rollout_from`.
Ещё AGENTS.md (карта кода, команды драйвера, «Переход в следующую
лабу» — `rollout_from`, таблица важных файлов) и `PLAN.md`,
`### attachments` («Решения» из apply). Проверка: `grep -rn
"c50b721" AGENTS.md .claude bench KNOWN_ISSUES.md` пуст.
- [x] 8.2 `make lint`, `make check`, `openspec validate attachments
--strict`, `graphify update .`. После sync дельт имя `attachments` —
и change, и спек: `openspec validate attachments --type change
--strict`.
## 9. Коммит, evidence, отчёт
- [x] 9.1 Финальная проверка на стенде `mtusi-lab4` после `make
rolling_update`:
- `make test` — `PASS: lab4`;
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make
test-failover ACTION_SCRIPT=scripts/stop-one.sh` — PASS, между
прогонами `make replicas`;
- `make student_test` и `make test_isolated` — красное только по
шапке;
- `make failure_checks` — код 0.
Затем показать изменения, предложить сообщение коммита и после
подтверждения закоммитить.
- [ ] 9.2 Evidence исключений с закоммиченного кода, без токенов,
паролей и секретов S3, в каждом файле дата, commit и стенд:
- четыре файла перехода по AGENTS.md («Переход в следующую лабу»).
`evidence/replicas/test-persistence.md` — `make test-persistence` с
`LAB=4`, `StartedAt` до и после, вложение после hook;
- `evidence/attachments/failover.md` — `attachment-failover`, оба
режима;
- `evidence/attachments/storage.md` — `attachment-storage`.
Проверка: `make student_test` — `test_exclusion_evidence_exists`
зелёный; `grep` по значениям секретов из `.env` в `evidence/` пуст.
Коммит — после подтверждения.
- [ ] 9.3 Evidence проверок по таблице решения 15:
- `evidence/tests/` — зелёные `make test_isolated`, `make
student_test` через LB, `make failure_checks`;
- `evidence/attachments/smoke.md`, `slow-transfer.md`;
- `evidence/failover/test-failover.md` — `make test-failover` с
`LAB=4` для каждой реплики, `STOP_ONE_LOG`, `docker compose ps` до
и после, между прогонами `make replicas`.
Проверка: в каждом файле команда, итог, дата, commit; секретов нет.
- [ ] 9.4 Желательно: `make bench_rollout ROLLOUT_LABEL=attachments`
после проверки хоста (`bench.md`, «Результаты»), рабочий стенд на
время замера остановлен. Проверка: код 0, в `summary.md` ревизии до и
после, сверка записей сошлась; метка закоммичена.
- [ ] 9.5 `REPORT.md` по решению 15:
- раздел о вложениях;
- соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS`;
- ответы на четыре вопроса защиты;
- строки уровней «3» и «4» с командой, наблюдением и файлом;
- ограничения;
- согласование с преподавателем 2026-10-20: текст из одних пробелов
с вложением — 201, без вложений — 400 (design, решение 8; AGENTS.md,
«Согласования с преподавателем»).
Строку этапа 2 в `PLAN.md` — по факту. Проверка: у каждой новой строки
таблицы доказательств есть команда, наблюдение и файл; `make lint`,
`make check`, `openspec validate attachments --strict`. Коммит — после
подтверждения.