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

23 KiB
Raw Blame History

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, исключения, проверка изображения

  • 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(…)" без ошибок.

  • 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. Схема БД

  • 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).

  • 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 и сервисы

  • 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.

  • 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.

  • 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

  • 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-ручки не изменились.

  • 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.

  • 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. Тесты

  • 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 его принимает.
  • 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.

  • 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 пропущен с причиной.

  • 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.

  • 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

  • 6.1 Команды upload и download по решению 13. Проверка против driver.py start и стенда (--port 8080): загрузка tests/fixtures/sample.png, скачивание вторым участником — SHA-256 99ea7533… совпадает; 404 постороннему; ruff format --check и make lint проходят.
  • 6.2 attachment-failover [--mode stop|kill] по решению 13. Проверка на стенде: оба режима — код 0, скачивание от реплики с другим X-Instance-Id, SHA-256 совпал, после команды снова API_REPLICAS реплик UP (make lb_stats). Отрицательная проверка: без балансировщика (--port консольного процесса) — код 2 и понятное сообщение.
  • 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.
  • 6.4 flow с вложением по решению 13, раздел о вложениях в SKILL.md: команды, gotchas — urllib напрямую к реплике и ранний 413; S3 нужен только путям вложений. Проверка: driver.py all — код 0, FAILED: none.

7. Стенд bench/

  • 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. Документы и проверка кода

  • 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 пуст.

  • 8.2 make lint, make check, openspec validate attachments --strict, graphify update .. После sync дельт имя attachments — и change, и спек: openspec validate attachments --type change --strict.

9. Коммит, evidence, отчёт

  • 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. Коммит — после подтверждения.