Files
mtusi2026lab4/openspec/changes/attachments/design.md
T
ricoromaandClaude Opus 5.5 dba40bc325 fix: address attachments verify findings
- keep one upload body in memory: BytesIO + getvalue() without copy,
  fixed glibc mmap threshold in the image (no realloc copy on growth)
- stop PNG inflate at expected size + 1 byte
- reject filename that is not valid UTF-8 after percent-decoding (400)
- failure stand: env limit variables do not change attachment limits;
  history with attachment_ids while S3 is stopped
- drop dead constants; restate "old image on new schema" scenario

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 02:16:49 +03:00

67 KiB
Raw Blame History

Design

Context

Мотивация — proposal.md, раздел Why. Требования — specs/.

Код — состояние после s3-storage (e1161f7):

  • клиент S3 src/infra/s3/ (put, open с чтением блоками, head, delete; срок на вызов и на блок, отказ — 503, ключи с префиксом имени базы);
  • отправка сообщения — одна транзакция: ключ идемпотентности, затем сообщение (MessageService.send_message);
  • история — keyset по индексу (chat_id, created_at, id);
  • ограничение ck_messages_text_length — char_length(text) BETWEEN 1 AND 4000.

Вложений нет ни в одном слое. Контракт лабы 4 сделал attachment_ids обязательным полем Message. Поэтому сейчас красные публичные make test, make test-persistence, make test-failover и 32 теста make student_test (PLAN.md, s3-storage → «Решения», п. 15).

Что найдено в коде до решений

Сессия БД держится весь запрос. get_db_session — зависимость с yield и областью «запрос». В FastAPI 0.141 такая зависимость закрывается после отправки ответа целиком: стек fastapi_inner_astack в fastapi/routing.py охватывает и await response(...). asyncio.timeout([database] request_timeout_seconds) (6 с) внутри неё покрывает всё: чтение тела, запись в S3, отдачу потока. authenticate делает SELECT без commit, и соединение пула остаётся занятым («idle in transaction») до конца запроса. Для загрузки и скачивания 10 MiB это значит:

  • медленный клиент обрывается на 6-й секунде, и в журнале это «Database is unavailable» (срок даёт TimeoutError, а is_db_unavailable считает его отказом БД);
  • через 10 с простоя транзакции PostgreSQL убивает соединение (idle_in_transaction_session_timeout);
  • 10 одновременных медленных передач занимают весь пул реплики (10 соединений), и остальные запросы получают 503 по сроку ожидания пула.

Отсюда решение 5.

Пробы (2026-10-20, scratchpad, проект compose attprobe, удалён)

Ранний ответ без чтения тела. Приложение-заглушка на образе mtusi-messenger:lab4 за HAProxy с infra/haproxy/haproxy.cfg проекта. Ответы 413 и 404 отдавались до чтения тела, по три прогона:

Клиент Напрямую к uvicorn Через HAProxy
httpx (клиент student-tests), тело 11 и 30 MiB с Content-Length и частями ответ получен, соединение переиспользуется ответ получен
curl с Expect: 100-continue 413, тело не отправлено (size_upload 0) так же
urllib (публичные проверки), 30 MiB BrokenPipe или ConnectionReset, ответ потерян ответ получен

Отказ по счётчику (413 после 10 MiB + 1) — тот же результат. HAProxy сам дочитывает остаток тела клиента, поэтому через LB ответ доходит до любого клиента.

Медленная передача через HAProxy. 9 MiB загрузки за 12,3 с и 10 MiB скачивания за 12,3 с прошли, коды 201 и 200. timeout server и timeout client считают простой, а данные шли. Значит, предел передачи — в приложении (выше), а не в LB.

Структурная проверка изображения. Прототип на stdlib (zlib, struct, re), Pillow 13.0.0 — для сравнения и генерации вариантов:

  • 17 настоящих вариантов приняты, все загружаются и Pillow:

    • PNG: RGB, RGBA, палитра, 1 бит, LA, 16 бит, чересстрочный;
    • JPEG: baseline, прогрессивный, с маркерами рестарта, серый, CMYK, 4:4:4, с EXIF;
  • отклонены как повреждённые: PNG и JPEG, обрезанные наполовину; PNG без последнего байта и без IEND (Pillow их грузит); изменённый байт IDAT (CRC); мусор после сигнатуры; JPEG без EOI; обрезанный прогрессивный; только заголовок;

  • приняты и прототипом, и Pillow: хвост после IEND и EOI; изменённый байт в данных скана JPEG — у формата нет контрольной суммы;

  • JPEG с подменёнными в SOF размерами 10000 × 5000 — 413 по заголовку. Pillow декодирует такой файл целиком: 150 МБ памяти из нескольких килобайт;

  • память и время прототипа на пиковых входах:

    Вход Итог Время Пик памяти
    PNG 1 × 40 000 000, 1 бит, «узкий» принят 305 мс 3,3 MiB
    PNG 8000 × 5000 RGBA из нулей, 160 МБ после распаковки принят 40 мс 3,5 MiB
    PNG 100 × 100, IDAT распаковывается в 200 MiB отклонён 0,4 мс 2,4 MiB
    JPEG, 10 MiB вставок FF 00 принят 111 мс 0
    настоящий PNG 7,6 МБ принят 20 мс 0,3 MiB

    Пик памяти — tracemalloc поверх тела.

  • корпус: 12 000 случайных PNG и JPEG из /System/Library, /Library и /Applications macOS:

    • 11 947 приняты и прототипом, и Pillow;
    • 38 отклонены обоими;
    • 2 отклонены только по лимиту пикселей: 8192 × 8192, 67 млн;
    • прототип не принял ни одного файла, который не загрузил бы Pillow.

    Первая версия проверяла фильтры строк циклом Python и на PNG 1 × 40 млн тратила десятки секунд. Срез с шагом строки сократил это до 0,3 с, конец данных скана JPEG ищет регулярное выражение — оба в C.

Goals / Non-Goals

Goals:

  • Все пункты рубрики «3» о вложениях и негативные тесты рубрики «4» (PLAN.md, этап 2), с зелёными публичными проверками лабы 4.
  • Порядок записи upload-consistency расширяет, а не переписывает: строка-намерение есть с первого дня.
  • Память одной загрузки ограничена телом и не зависит от числа пикселей. Ни одно соединение пула PostgreSQL не занято на время передачи байтов.
  • Прежние профили bench/ и проверки лаб 2–3 работают, rollout показывает замену на схему с вложениями.

Non-Goals:

  • Компенсация после PUT, уборщик, его S3-пользователь и частичный индекс зависших pending, тесты отказов посреди загрузки — upload-consistency.
  • Лимит одновременных загрузок, сроки чтения тела, подбор срока PUT под очередь S3, профиль uploads — upload-memory.
  • Декодирование пикселей и варианты (thumbnail) — lab5. Проверка здесь структурная (решение 2).
  • Range, ETag, Content-Disposition и кэширование ответа download: контракт их не требует.

Decisions

1. Порядок записи и граница с upload-consistency

Загрузка (AttachmentService.upload):

  1. Проверки до чтения: членство в чате, Content-Type, Content-Length.
  2. Чтение тела со счётчиком (решение 6).
  3. Проверка содержимого и SHA-256 в потоке (решение 2).
  4. Транзакция 1: строка attachments в статусе pending с object_key, commit.
  5. PUT объекта.
  6. Транзакция 2: UPDATE … SET status = 'ready', updated_at = now WHERE id = … AND status = 'pending' RETURNING …, commit.
  7. 201 с этой строкой.

Отказы:

Где Ответ Что остаётся
шаги 1–3 (401, 400, 404, 413, 415, обрыв тела) 4xx ничего: до шага 4 запись не идёт
шаг 4 (БД) 503 ничего
шаг 5 (S3 недоступен, срок, отказ) 503 строка pending; объекта нет, или он записан после истечения срока
шаг 6 (БД) 503 строка pending и объект

Строку pending API не показывает: метаданные и байты — 404, ссылка в сообщении — 404. В этом change её никто не убирает. upload-consistency добавит компенсацию (DELETE объекта после неудачи на шагах 5–6, без гарантии), уборщик с grace period и тесты отказов посреди загрузки. Он меняет только ветки ошибок, порядок шагов остаётся. Если шаг 6 не нашёл строку pending, значит её удалил кто-то другой. Без уборщика это невозможно, поэтому RuntimeError (500), как «Idempotency key disappeared» в send_message. Ветку переопределяет upload-consistency.

Ответ на вопрос защиты «PUT прошёл, COMMIT нет»: строка pending с ключом уже в БД, объект не «вечный неучтённый», его найдёт уборщик по строке. Объект без строки возможен только мимо API — класс расхождений трека 2.

Альтернатива: PUT, затем одна вставка строки ready. Отвергнута: сбой commit оставляет объект, о котором БД не знает. Найти его можно только списком bucket, а у ключа API права List нет. upload-consistency пришлось бы переписывать поток и миграцию. Альтернатива: транзакция, открытая на время PUT. Отвергнута: соединение и блокировка держатся до 5 с, а сбой commit после PUT всё равно оставляет объект. Альтернатива: компенсация уже здесь. Отвергнута: без уборщика и тестов отказов посреди загрузки это половина механизма. Её тесты — upload-consistency.

2. Проверка изображения: структура без декодирования

Чистая функция inspect_image(data, *, max_pixels) -> ImageInfo в src/utils/image.py, только stdlib. По образцу src/utils/cursor.py она бросает свои исключения (UnsupportedImage, DamagedImage, TooManyPixels от ImageError(ValueError)), а сервис переводит их в доменные (415, 415, 413). Порядок:

  1. Сигнатура: \x89PNG\r\n\x1a\n — PNG, FF D8 FF — JPEG, иначе UnsupportedImage.
  2. PNG:
    • IHDR первым, 13 байт, глубина допустима для типа цвета, методы сжатия и фильтра 0, чересстрочность 0 или 1;
    • размеры больше 40 млн пикселей — TooManyPixels до любой распаковки;
    • каждый чанк: длина в пределах файла, CRC (zlib.crc32);
    • неизвестный критичный чанк (первая буква заглавная) — повреждение;
    • PLTE до IDAT и обязателен для типа 3;
    • IDAT подряд, поток распаковывается zlib.decompressobj блоками с max_length 1 MiB. Выход больше ожидаемого — повреждение, сразу. Ожидаемое — строки × (1 + байт в строке), по проходам Adam7 для чересстрочного;
    • тип фильтра строки ≤ 4: срез распакованного блока с шагом длины строки, проверка в C, без цикла Python по строкам;
    • на IEND: поток завершён (eof) и распакован ровно в ожидаемый объём. Остаток после конца потока zlib в IDAT допускается: libpng считает его безвредным.
  3. JPEG:
    • сегменты с длинами, байты-заполнители FF;
    • один SOF (C0–C3, C5–C7, C9–CB, CD–CF), ненулевые размеры, 1–4 компонента, длина сегмента сходится с числом компонент;
    • больше 40 млн пикселей — TooManyPixels сразу на SOF;
    • SOS после SOF; конец данных скана — первая серия FF, за которой не 00 и не RST0–7, ищется регулярным выражением;
    • EOI обязателен.
  4. Байты после IEND или EOI допускаются и остаются частью оригинала.

Проверка, SHA-256 и подсчёт идут одним вызовом anyio.to_thread.run_sync. Распаковка zlib и SHA-256 отпускают GIL, event loop не стоит. Свой лимитер, как у KDF, здесь не нужен: память проверки — единицы MiB (Context). Лимит одновременных загрузок — upload-memory.

Что это значит для клиента, записано в спеке attachments, «Повреждённое изображение»:

  • обрезанный файл, битая CRC, сломанная структура маркеров, поток zlib не того объёма и «бомба» — 415;
  • изменённый байт внутри данных скана JPEG не ловится. Его не ловит и Pillow: libjpeg выдаёт предупреждение и рисует мусор;
  • хвост после конца изображения допускается.

Подтверждено пользователем 2026-10-20 (PLAN.md, ### attachments → «Вопросы», п. 1): структурная проверка, без полного декодирования.

Альтернатива: полное декодирование Pillow (Image.load()). Отвергнута:

  • 40 млн пикселей RGBA — 160 МБ на загрузку при лимите реплики 512 МБ;
  • нужен семафор уже в этом change;
  • Pillow не ловит ни битый скан JPEG, ни отсутствие IEND (Context);
  • ещё ~10 МБ нативных библиотек в образе.

Pillow понадобится worker лабы 5, у него будет свой бюджет памяти. Альтернатива: Pillow verify(). Отвергнута: для JPEG почти ничего не проверяет, для PNG не распаковывает IDAT, «бомбу» не видит. Альтернатива: только сигнатура и размеры из заголовка. Отвергнута: обрезанный файл проходил бы, а рубрика «4» требует теста на повреждённое изображение. Альтернатива: pypng и аналоги. Отвергнута: чистый Python построчно — секунды на 40 млн пикселей.

3. Схема БД

Ревизия alembic поверх e656d6bbe1a4, первая строка — SET LOCAL lock_timeout = '2s' (migrations.md).

attachments:

Колонка Тип Ограничения
id uuid PK, назначает сервис
chat_id, owner_id uuid FK (chat_id, owner_id) → chat_members(chat_id, user_id): владелец — участник чата
filename text char_length 1–255; без /, \ и управляющих символов категории Cc — U+0001–U+001F и U+007F–U+009F, NUL в text PostgreSQL не бывает (то же правило, что в API, решение 10; литерал регулярного выражения проверяется в apply вставками через psql)
content_type text IN ('image/png', 'image/jpeg')
size_bytes integer 1–10 485 760
sha256 bytea octet_length = 32, как request_hash и token_hash
object_key text уникальный, octet_length 1–1024 (предел ключа S3)
status text IN ('pending', 'ready'); lab5 расширит список заменой CHECK
created_at, updated_at timestamptz updated_at >= created_at

message_attachments — связь с порядком:

Колонка Тип Ограничения
message_id uuid FK → messages(id)
position smallint 0–9, PK (message_id, position)
attachment_id uuid FK → attachments(id), уникальна пара (message_id, attachment_id), индекс по attachment_id
created_at timestamptz время сообщения, как chat_members.created_at — время чата (Base даёт колонку всем моделям)

Индекс по attachment_id нужен двум вещам: удалению строки pending уборщиком (иначе проверка FK — полный просмотр связей) и вопросу «на вложение ссылаются сообщения?» reconciler-а трека 2. FK без ON DELETE: вложение, на которое ссылается сообщение, БД удалить не даст. Это гипотеза безопасности 5 трека 2 на уровне ограничения.

messages: ck_messages_text_length заменяется ограничением с тем же именем и условием char_length(text) <= 4000, NOT VALID. Модель — CheckConstraint(..., name="text_length") с новым условием. Прежние строки удовлетворяли более строгому условию, проверять их нечего. VALIDATE держал бы ACCESS EXCLUSIVE, пока идёт полный просмотр таблицы, а это все реплики без записи. Вне транзакции миграции его не сделать: autocommit_block alembic зафиксирует DDL раньше alembic_version, и сбой оставил бы неповторяемую миграцию. Новые строки NOT VALID проверяет так же. Отметка «не проверено» в каталоге — цена, она описывается в REPORT.md. Это ослабление ограничения, поэтому дельта db-migrations разрешает его как расширение. Правило «непустой текст или хотя бы одно вложение» — в сервисе: в одной строке messages числа вложений нет.

Принадлежность вложения чату сообщения проверяет сервис в той же транзакции, что и вставку связи. Чат вложения и чат сообщения не меняются, поэтому проверка не устаревает до commit.

Альтернатива: массив uuid[] в messages. Отвергнута: у элементов массива нет FK, и БД не держит ни существование вложения, ни запрет удаления используемого. Обратный поиск — только GIN-индекс. Альтернатива: chat_id в связи и составные FK на attachments(id, chat_id) и messages(id, chat_id). Отвергнута: второму FK нужен уникальный индекс (id, chat_id) на messages, третий индекс на самой горячей таблице. Он дорожает каждую запись, в том числе без вложений, ради правила, которое сервис держит на неизменяемых данных. Альтернатива: тип ENUM для статуса. Отвергнута: ALTER TYPE … ADD VALUE нельзя использовать в той же транзакции, text + CHECK проще расширять.

4. Ключ объекта

<namespace>/attachments/<attachment_id>/original:

  • namespace — имя базы (ObjectStorage.namespace, s3-storage);
  • id — uuid4() сервиса;
  • original оставляет место вариантам lab5 под тем же префиксом.

Ключ собирает repo src/core/repos/attachment_object.py (repo над S3, как chat_cache.py над Valkey) и хранится в attachments.object_key. Путь в S3 не выводится из строки при каждом чтении, поэтому:

  • уборщик и reconciler читают ключ из строки, а страница LIST сверяется запросом object_key = ANY(...) по уникальному индексу (PLAN.md, гипотеза 2 трека 5);
  • смена схемы ключей в lab5 (staging-префикс) не трогает прежние строки.

filename в ключ не входит, ключ в ответы API не попадает. make test_isolated пишет под test_<db>/attachments/… и убирает префикс test_<db>/ (s3-storage).

Альтернатива: отдельный случайный ключ, не связанный с id. Отвергнута: bucket приватный, у ключа API нет List, а ключ, связанный с id, ещё и читается reconciler-ом без БД. Альтернатива: ключ не хранить, вычислять из id. Отвергнута по двум пунктам выше.

5. Длинные запросы без сессии БД на всё время

  • db_session_scope() в src/api/dependencies.py — асинхронный контекст с телом нынешнего get_db_session: asyncio.timeout([database] request_timeout_seconds), is_db_unavailable → invalidate(), warning и ServiceUnavailable. get_db_session превращается в обёртку над ним, поведение остальных ручек прежнее.
  • get_current_user_brief (тип CurrentUserBrief): Bearer из той же bearer_scheme → async with db_session_scope() → SessionService.authenticate → выход из контекста (откат, соединение в пул) → current_user_id и пользователь. Это обычная функция, а не генератор: сессия закрыта до тела запроса.
  • AttachmentService(db_scope, cache, storage):
    • db_scope — вызываемый объект, возвращающий такой контекст (db_session_scope);
    • storage — глобал object_storage. Его, как и прежде, импортирует только dependencies.py;
    • каждый шаг с БД — свой короткий async with self.db_scope();
    • вложенных контекстов нет: в каждый момент на запрос не больше одного соединения пула, взаимной блокировки пула быть не может.
  • Ручки вложений — загрузка, метаданные, байты — берут только CurrentUserBrief и AttachmentServiceDep, без DbSessionDep.

Срок 6 с остаётся на каждом шаге с БД. Передача байтов ограничена сроками S3 ([s3] timeout_seconds на вызов и на блок чтения) и таймаутами LB. Срок чтения тела от клиента — upload-memory.

Правило service-layer.md «__init__ принимает db_session» для AttachmentService меняется: правка правила — задача apply.

Альтернатива: сессия запроса и commit() сразу после проверки токена. Отвергнута: соединение вернётся, но asyncio.timeout в get_db_session по-прежнему охватывает передачу (Context). Альтернатива: Depends(get_db_session, scope="function"). Отвергнута: контекст закрывается после выхода из функции ручки, а чтение тела и PUT идут внутри неё. Альтернатива: поднять request_timeout_seconds. Отвергнута: слабеет защита от зависшего PostgreSQL у всех ручек, а соединение всё равно занято передачей. Альтернатива: срок на каждый вызов repo во всех сервисах. Отвергнута: большая переделка без нужды для коротких JSON-ручек.

6. Чтение тела, ответы до чтения

  • Ручка передаёт сервису media_type из Content-Type (часть до ;, без пробелов, в нижнем регистре), Content-Length (int или None) и асинхронный итератор тела. Итератор — обёртка над request.stream(), которая переводит ClientDisconnect Starlette в доменное UploadInterrupted (400). Клиента уже нет, но в итоговой записи запроса будет 400, а не 500 с traceback.

  • Сервис:

    • media_type не PNG и не JPEG — 415 до тела;
    • Content-Length больше лимита — 413 до тела;
    • чтение в io.BytesIO со счётчиком: больше лимита — 413 сразу, без дочитывания;
    • затем getvalue() — bytes над тем же буфером, без копии (CPython отдаёт внутренний объект, если на буфер нет ссылок). Именно bytes: botocore оборачивает тело PutObject в BytesIO без копии только для bytes, а bytearray копирует (httpchecksum), inspect_image и hashlib принимают оба.
  • Пик памяти загрузки — одно тело и блок чтения, пока не отработал PUT; botocore читает тело для подписи и CRC32 блоками по 1 MiB. Рост буфера без копии в образе даёт MALLOC_MMAP_THRESHOLD_=131072 (Dockerfile): с динамическим порогом glibc после первой загрузки растит буфер в куче, и realloc на миг держит два тела. Замер — «Уточнения apply», п. 10. Сколько таких загрузок помещается в 512 МБ и чем их ограничить — upload-memory.

    Альтернатива: сразу выделить буфер под Content-Length. Отвергнута: клиент, заявивший 10 MiB и не шлющий тело, держал бы 10 MiB с первого байта, а не по мере передачи.

  • Content-Length: 0 и пустое тело — 415 (не изображение).

  • Ответы 404, 413 и 415 до чтения тела доходят до httpx, до curl и до любого клиента через LB (Context). urllib напрямую к одной реплике ответ теряет: ограничение, записывается в REPORT.md. Публичные проверки больших тел не шлют.

  • Порядок проверок — спек «Порядок проверок загрузки». 401 и 400 (chat_id, filename) даёт FastAPI: параметры проверяются после зависимостей, как у сообщений (api-contract.md). 404 и остальное — сервис.

7. Скачивание

  • Сервис open_content:
    1. Короткая транзакция: строка вложения в статусе ready и членство в его чате через ChatService.get_chat_for_member (кэш карточки). Нет строки, не ready или не участник — AttachmentNotFound (404).
    2. Вне транзакции: object_storage.open(key) — GET с заголовками. Отказ S3 — 503 ещё до заголовков ответа API.
    3. Нет объекта (StoredObjectMissing) или размер в S3 не равен size_bytes — error «Attachment content is missing» или «…size differs» с attachment_id и ключом, затем AttachmentContentMissing (500 internal_error). Строку сервис не меняет: промах не основание для разрушающего решения (PLAN.md, s3-storage → «Вопросы», п. 4). Как помечать такие строки, решит reconciler трека 2.
    4. DTO с типом, размером и асинхронным генератором блоков StoredObject.iter_chunks() (срок на блок — клиент S3).
  • Ручка — StreamingResponse:
    • media_type — content_type вложения: у image/* Starlette не добавляет charset;
    • Content-Length из size_bytes, X-Content-Type-Options: nosniff;
    • variant: Literal["original"] = "original": иное значение — 400 по схеме, как перечисление контракта лабы 4.
  • Генератор закрывает объект в finally, когда поток дочитан, оборван клиентом или упал. Если генератор так и не начался, тот же закрыватель вызывает фоновая задача ответа. Закрытие повторно безопасно.
  • Отказ S3 посреди потока: статус уже ушёл. Соединение обрывается, клиент получает тело короче Content-Length, в журнале — запись клиента S3 и ошибка ASGI. Иначе нельзя без буферизации всего файла.

Альтернатива: прочитать объект целиком и отдать Response. Отвергнута: до 10 MiB в памяти на каждое скачивание. Альтернатива: redirect на подписанный URL. Отвергнута: контракт требует отдачи без redirect, S3 вне сети клиента.

8. Сообщения с вложениями

  • CreateMessage:

    • text: StrictStr, до 4000 code points;
    • attachment_ids: list[UuidIn], по умолчанию [], max_length 10;
    • валидатор модели: повтор id (сравнение UUID, регистр не важен) — 400; пустой текст — "" или из одних пробельных символов (not text.strip()) — без вложений 400, с хотя бы одним вложением допустим (спек messages, «Валидация текста»). Текст не обрезается и не нормализуется.

    Согласовано с преподавателем 2026-10-20 (AGENTS.md, «Согласования с преподавателем»; PLAN.md, ### attachments → «Вопросы», п. 2). Контракт был неоднозначен: общее правило «обязательные строки не из одних пробелов» (contracts/README.md, строка 9) против «нельзя … пробельный текст без вложений» (строка 18). Ответ: «пустой текст» — и "", и строка из одних пробелов; с вложением он допустим, без вложений — 400. До ответа действовала временная трактовка «пробелы с вложением — 400»; её сменила эта.

  • MessageService.send_message(..., attachment_ids):

    1. членство;
    2. вложения: attachment_repo.get_attachments(ids) — не больше 10 строк по первичному ключу. Все найдены, у всех чат этого сообщения, статус ready. Иначе AttachmentNotFound (404) до захвата ключа: ошибка не занимает ключ;
    3. хэш, захват ключа, вставка сообщения;
    4. message_repo.insert_message_attachments — одна многострочная вставка с position;
    5. один commit.
  • MessageFullDTO получает attachment_ids: tuple[UUID, ...] = (). Вставка сообщения перечисляет свои колонки явно, а не **asdict(message).

  • Чтение: в MESSAGE_COLUMNS — коррелированный подзапрос ARRAY(SELECT attachment_id FROM message_attachments WHERE message_id = messages.id ORDER BY position) AS attachment_ids. Это одно выражение на страницу (repo-layer.md), им же читает сохранённый результат idempotency_repo.get_key_result. План — SubPlan с индексом pk_message_attachments на каждую строку страницы, индекс истории прежний. В apply проверяется EXPLAIN (ANALYZE, BUFFERS).

  • Разбор журнала bench/run.py с новым запросом сверен по коду:

    • INDEX_NODE_RE берёт первый узел индекса: SubPlan EXPLAIN печатает после потомков, поэтому первым остаётся индекс messages;
    • or_cursor меняет только условие WHERE;
    • plan_summary ищет узел on messages, а on message_attachments с ним не совпадает.

    Регресс — make bench_quick.

  • Журнал: Created message получает attachments_count.

9. Хэш идемпотентности

message_request_hash(text, attachment_ids):

  • канонический JSON {"text": t}, при непустом списке — ещё "attachment_ids": [str(id), …];
  • str(UUID) пишет нижний регистр, поэтому регистр в запросе хэш не меняет, а порядок элементов меняет;
  • пустой список не меняет хэш: ключ, сохранённый версией e1161f7, повторяется после make rolling_update без 409 (PLAN.md, решение 6).

Повтор отдаёт сохранённое сообщение с его attachment_ids (решение 8).

10. Слой API и ошибки

  • src/api/routers/v1/attachment.py: APIRouter(tags=["attachments"]) с полными путями /chats/{chat_id}/attachments и /attachments/{attachment_id}[/content], подключение в routers/v1/__init__.py. Два префикса в одном роутере — отличие от api-layer.md, правило дополняется.

  • Загрузка:

    • request: Request без параметра тела — FastAPI тело не читает;

    • openapi_extra с requestBody image/png и image/jpeg (format: binary), как в контракте: так /docs показывает загрузку;

    • filename — Query(min_length=1, max_length=255) над типом DisplayFilename в src/api/schemas/attachment.py. Его AfterValidator отклоняет /, \, управляющие символы категории Cc (U+0000–U+001F, U+007F–U+009F; unicodedata.category(ch) == "Cc") и строку из одних пробелов. Остальное принимается: символы форматирования и направления текста (Cf), разделители U+2028 и U+2029 (Zl, Zp), ZWJ.

      Альтернатива: отказ ещё и на символы направления текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028, U+2029). Ими подменяют видимое имя: U+202E перед gnp.exe показывает его задом наперёд. Отвергнута решением пользователя 2026-10-20 (PLAN.md, ### attachments → «Вопросы», п. 3):

      • контракт называет только /, \, NUL и управляющие символы, и отказ сверх списка — расхождение с ним;
      • эти символы встречаются и в законных именах на языках с письмом справа налево;
      • имя только отображается, ни в ключ, ни в путь не попадает, а изолировать направление текста при показе может клиент.
  • Модель ответа Attachment:

    • sha256 — hex из bytes DTO;
    • status: Literal["ready"], variants — всегда [], error_code: None;
    • времена — UtcDatetime;
    • лишних полей нет, object_key в модель не входит.
  • Доменные исключения в src/core/exceptions/attachment.py и строки таблицы errors.py:

    Исключение Ответ
    AttachmentNotFound 404 not_found, «Not found»
    PayloadTooLarge 413 payload_too_large
    UnsupportedMediaType 415 unsupported_media_type
    UploadInterrupted 400 invalid_request
    AttachmentContentMissing 500 internal_error, «Internal server error»

    Тексты — на английском, без внутренних деталей.

  • Константы в src/utils/constants.py:

    • лимиты: ATTACHMENT_MAX_BYTES 10 485 760, ATTACHMENT_MAX_PIXELS 40 000 000, длины filename, MESSAGE_ATTACHMENTS_MAX 10;
    • ключ объекта: префикс attachments, суффикс original;
    • запрещённые символы filename: /, \ и категория Cc.
  • Enum AttachmentStatus (pending, ready) и ImageType (image/png, image/jpeg) — src/schemas/enums/attachment.py. DTO AttachmentFullDTO, AttachmentContentDTO — src/schemas/dataclasses/ attachment.py.

  • MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS skeleton — эти константы, не настройки (дельта service-configuration). Соответствие — в REPORT.md, .env.example их не заводит.

11. Журнал

  • Модуль attachment_service:
    • info «Uploaded attachment»: attachment_id, chat_id, size_bytes, content_type, width, height, duration_ms;
    • info «Rejected attachment»: причина (type, declared_size, size, content_mismatch, damaged, pixels, interrupted), chat_id и длина filename;
    • error о пропавшем объекте — решение 7.
  • filename и байты не пишутся (дельта service-logging), ключ объекта допустим (logging.md).

12. Тесты

  • pillow — только dev-группа (uv add --dev pillow): генерация JPEG разных видов в памяти теста. В образ (uv sync --no-dev) и в приложение не входит.

  • student-tests/images.py — генераторы:

    • PNG на stdlib с любыми IHDR и IDAT, Adam7, чанком-заполнителем tEXt до точного размера (10 485 760 и +1), «бомбой», порчей CRC, обрезкой и хвостом;
    • JPEG через Pillow с подменой размеров в SOF, обрезкой и хвостом.

    Большие и «бомбы» в git не попадают (tests/fixtures/README.md).

  • test_attachments.py — сценарии спека attachments, маркеры spec. «Скачивание через другую реплику» — с фикстурой replicas: скачивать, пока ответ не придёт с другим X-Instance-Id.

  • test_rubric.py — пять сценариев рубрики «4» лабы 4 (дельта student-tests) с маркерами сценариев attachments и messages.

  • Дополняются:

    • test_messages.py, test_idempotency.py, test_api_conventions.py, test_data_storage.py — новые сценарии дельт;
    • api_client.py — загрузка, метаданные, байты, send_message(..., attachment_ids=…);
    • contract.py:
      • коды 413 и 415;
      • owner_id и элементы attachment_ids — UUID в нижнем регистре, updated_at — время;
      • assert_content для бинарного ответа.
  • Проверки отказов (test_failures.py): «Запись в S3 не удалась», «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 завис».

    • Новые действия hook: count-attachments (pending=N ready=M через psql) и count-objects (число каталогов вложений в /buckets/<bucket>/<db>/attachments через filer на loopback контейнера s3). Bucket и базу hook получает от run_failures.py в окружении.
    • Срок «S3 завис» — [s3] timeout_seconds (5 с) плюс запас.
  • Сверка покрытия: attachments в CAPABILITIES. Исключения с доказательствами:

    • «Принявшая реплика остановлена» → driver.py attachment-failover, evidence/attachments/failover.md;
    • «Байты не в БД и не на диске API» → driver.py attachment-storage, evidence/attachments/storage.md;
    • «Рестарт стенда» → make test-persistence, evidence/replicas/test-persistence.md: публичная проверка с LAB=4 скачивает оригинал после hook.
  • Дельты, на сценарии которых ставят маркеры, синхронизируются в основные спеки в apply (/opsx:sync), как health в s3-storage: сверка читает только openspec/specs/.

13. Драйвер скилла run-mtusi-messenger

Только stdlib, Python 3.9.

  • upload --token T --chat C --file F [--type …] [--filename …] — статус, X-Instance-Id, тело, SHA-256 файла.

  • download --token T --attachment A [--out F] [--variant …] — статус, X-Instance-Id, Content-Type, размер, SHA-256 полученного.

  • attachment-failover [--mode stop|kill] — стенд с LB:

    1. синтетические Алиса, Боб, Ева, чат;
    2. загрузка tests/fixtures/sample.png, реплика A;
    3. сообщение со ссылкой;
    4. scripts/stop-one.sh с TARGET_INSTANCE_ID=A;
    5. Боб скачивает через LB: ответ от B ≠ A, SHA-256 совпадает;
    6. Ева — 404;
    7. в finally — make replicas.

    Вывод — docker compose ps до и после и таблица без токенов. Код 1 при любом расхождении.

  • attachment-storage — стенд с LB:

    • загрузки через LB;
    • psql: колонки и типы таблиц вложений (нет колонки с байтами, кроме 32-байтного SHA-256), вид object_key, filename не в ключе;
    • weed shell / filer: объект есть;
    • анонимный GET ключа с 127.0.0.1:S3_OUT_PORT: 403;
    • docker diff каждой реплики: файлов оригиналов нет.

    Пункты 2 и 4 сценария защиты.

  • flow загружает fixture, отправляет сообщение с вложением, скачивает его как Боб (SHA-256) и проверяет 404 Евы.

14. Профиль rollout и rollout_from

  • Profile.rollout_from = "e1161f7": последний commit лабы 4 до attachments. Замена показывает миграцию вложений с ослаблением ограничения под нагрузкой.
  • До сборки стенда — git rev-parse <commit>^{commit}. Commit не найден — BenchError с commit и подсказкой --from (дельта load-benchmark), а не падение на шестой секунде.
  • Правило в bench.md и AGENTS.md («Переход в следующую лабу»): rollout_from меняется при переходе в лабу и когда замена должна показать новое изменение схемы.
  • Запись KNOWN_ISSUES.md о c50b721 удаляется.
  • Evidence — make bench_rollout ROLLOUT_LABEL=attachments (желательно, PLAN.md): старые реплики на новой схеме, одна миграция, ошибки по секундам.
  • Нагрузка профиля — запись и чтение сообщений, S3 стенд bench/ не запускает. Методика прежняя (bench.md).

15. Evidence и отчёт

Файл Что
evidence/attachments/smoke.md make test (PASS: lab4), driver.py upload / download Бобом с SHA-256, 404 Евы на метаданные и байты
evidence/attachments/failover.md driver.py attachment-failover в режимах stop и kill
evidence/attachments/storage.md driver.py attachment-storage: схема, ключи, объект, анонимный 403, docker diff
evidence/attachments/slow-transfer.md разовый скрипт: 10 MiB загрузки и скачивания через LB дольше 6 с проходят (решение 5)
evidence/failover/test-failover.md make test-failover с LAB=4 для каждой реплики, STOP_ONE_LOG, docker compose ps до и после
evidence/cache/hits.md, evidence/auth/passwords-and-tokens.md, evidence/replicas/test-persistence.md, evidence/idempotency/replay-after-restart.md исключения сверки, сняты на стенде лабы 4 (AGENTS.md, «Переход в следующую лабу»)
evidence/tests/ зелёные make test_isolated, make student_test через LB, make failure_checks
evidence/rollout/attachments/ make bench_rollout с e1161f7 на схему с вложениями (желательно)

REPORT.md:

  • раздел о вложениях: схема потока, порядок записи и таблица отказов, проверка изображения и её граница, схема БД и ключ;
  • соответствие MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS;
  • ответы на четыре вопроса защиты;
  • строки уровней «3» и «4» с командой, наблюдением и файлом;
  • ограничения: структурная проверка, NOT VALID, urllib напрямую, смешанные версии при замене;
  • согласование с преподавателем 2026-10-20: текст из одних пробелов с вложением — 201, без вложений — 400 (решение 8, AGENTS.md, «Согласования с преподавателем»).

Risks / Trade-offs

  • [Структурная проверка не ловит искажения внутри данных скана JPEG] → граница названа в спеке и REPORT.md. Pillow её тоже не ловит. Lab5 декодирует оригинал в worker, и такой файл получит статус failed.
  • [Свой разборщик отклонит настоящий файл] → корпус 12 000 файлов без ложных отказов (Context); в тестах матрица вариантов; в apply корпус гоняется ещё раз на готовом src/utils/image.py.
  • [CPU проверки: до ~0,3 с на «узкий» PNG и ~0,1 с на JPEG из вставок] → в потоке, event loop не стоит. Лимит параллельных загрузок — upload-memory.
  • [Память загрузки ~1,2 тела (тело и блоки чтения botocore) без лимита конкурентности: около 30 одновременных загрузок по 10 MiB (~12,5 МБ каждая сверх ~120 МБ базы реплики) доводят реплику 512 МБ до OOM] → граница описана, лимит и замер — upload-memory. До него нагрузочные прогоны загрузок не запускаются.
  • [PUT 10 MiB со сроком 5 с: под очередью S3 последняя из 20 одновременных записей подтверждена через 7,2 с] → 503 и строка pending, клиент повторяет загрузку. Срок PUT и лимит конкурентности — upload-memory, объекты таких отказов — upload-consistency.
  • [После тела LB ждёт ответа timeout server (10 с), а худший путь — шаг БД, PUT до 5 с и ещё шаг БД] → обычно десятки миллисекунд. В худшем случае клиент получает 504 от LB, а API может довести загрузку до ready. Повтор клиента создаёт второе вложение — контракт это допускает. Цепочку пересматривает upload-memory.
  • [Нет срока чтения тела: медленный клиент держит загрузку] → ни соединения пула, ни транзакции он не держит (решение 5), память — до лимита. Срок — upload-memory.
  • [Строки pending копятся до уборщика] → только при отказах S3 и БД посреди загрузки. Их видно счётчиком hook. Уборщик — upload-consistency, следующий change.
  • [Смешанные версии при make rolling_update: старая реплика отвечает 404 на пути вложений и 400 на attachment_ids, а сообщения отдаёт без attachment_ids] → окно замены; описывается в REPORT.md. Откат на e1161f7 (MIGRATE=0) прячет вложения и показывает пустые тексты сообщений с вложениями: схема при этом не откатывается.
  • [NOT VALID в каталоге] → смысл ограничения тот же. Проверить существующие строки можно отдельной миграцией, когда это понадобится.
  • [urllib напрямую к одной реплике теряет ранний 413] → через LB доходит; тесты на httpx; ограничение в REPORT.md.
  • [Дельты синхронизируются в основные спеки до archive] → если /opsx:verify поменяет дельты, sync повторяется; archive не дублирует требования.
  • [Обрыв S3 посреди скачивания обрывает ответ после заголовков] → клиент видит тело короче Content-Length, в журнале — причина.

Migration Plan

  1. Константы, enum, DTO, исключения, src/utils/image.py.
  2. Модели и ревизия alembic: autogenerate, затем руками ограничение NOT VALID и lock_timeout. Проверки — с нуля, повторно и под записью прежней версии.
  3. Repo, сервисы, зависимости, ошибки, схемы и ручки API.
  4. Драйвер, тесты, hook стенда отказов, sync дельт, make lint, прогоны.
  5. rollout_from, регресс bench/.
  6. Правила, AGENTS.md, скилл, KNOWN_ISSUES.md, PLAN.md.
  7. Commit после подтверждения пользователя, затем evidence, затем REPORT.md — каждый шаг отдельным commit с подтверждения.

На рабочем стенде новый код — make rolling_update: одна миграция, затем замена по одной. Bootstrap S3 не меняется, переменных в .env не добавляется.

Откат — make rolling_update COMMIT=e1161f7 MIGRATE=0. Схема остаётся: прежний код таблиц вложений не знает, ослабленное ограничение ему не мешает. Загруженные вложения остаются в БД и S3 и снова видны после возврата вперёд.

Уточнения apply

  1. src/utils/image.py на готовом модуле (задача 1.2, 2026-10-20, scratchpad, Pillow 13.0.0 через uv run --no-project --with pillow): 17 вариантов приняты (PNG RGB, RGBA, палитра, 1 и 2 бита, LA, 16 бит, серый, Adam7; JPEG baseline, прогрессивный, с RST, серый, CMYK, 4:4:4, EXIF); повреждённые из Context — DamagedImage (PNG без последнего байта и без IEND Pillow грузит); хвосты и байт скана JPEG приняты; SOF 10000 × 5000 и IHDR 40 000 001 — TooManyPixels; «бомба» — 1,0 мс, PNG 1 × 40 млн — 56 мс, 8000 × 5000 RGBA — 27 мс, JPEG из FF 00 10 MiB — 40 мс, пик tracemalloc ≤ 3,2 MiB; корпус 12 000 файлов: 11 964 приняты обоими, 34 отклонены обоими, 2 — только по лимиту пикселей, ложных отказов 0. Вход IDAT подаётся кусками по 64 KiB: иначе unconsumed_tail копирует остаток большого чанка на каждом блоке выхода.
  2. План истории (задача 7.2): на стенде bench/ таблица message_attachments пуста, и SubPlan идёт Seq Scan по пустой таблице (0 страниц) — индекс истории прежний (explain-10k.txt пробной метки). С данными (20 000 сообщений, 40 000 связей в откатываемой транзакции на рабочей базе) SubPlan — Bitmap Index Scan on pk_message_attachments, 51 цикл, страница 0,2 мс. Решение 8 этим подтверждено; формулировку задачи 7.2 («SubPlan по pk_message_attachments») пустая таблица стенда не показывает.
  3. Причины отказа загрузки в журнале (решение 11): к списку добавлена content — содержимое не PNG и не JPEG (UnsupportedImage), отдельно от damaged (структура нарушена) и content_mismatch (тип содержимого не совпал с Content-Type).
  4. variant в /openapi.json: Literal["original"] pydantic пишет как const; Query(json_schema_extra={"enum": ["original"]}) добавляет перечисление контракта.
  5. Тест «S3 завис»: клиент Api набора со сроком 5 с обрывал запрос раньше ответа API (503 через 5,0 с). Тест берёт клиента со сроком 15 с — дефект теста, не приложения.
  6. Имя ограничения в ревизии: drop_constraint без op.f(...) применял шаблон имён и искал ck_messages_ck_messages_text_length (видно в upgrade --sql); исправлено до применения.
  7. Тексты из пробелов с вложением — ответ преподавателя 2026-10-20 пришёл во время apply (решение 8): валидатор сразу написан под 201; «сначала красный» тест на прежнем валидаторе не показывался — прежней версии с вложениями не было.
  8. bench_restore_quick (задача 7.2) падал из-за гонки стенда, не кода вложений: switch_api пересоздаёт реплику с тем же IP, и wait_ready видел устаревший UP слота от прежнего контейнера (3 из 4 полных прогонов на размере 10k; журнал LB: ECONNREFUSED → DOWN → 503 <NOSRV> на запросы k6, процесс поднялся через ~0,7 с).
  9. Исправление гонки — в этом change (решение основной сессии 2026-10-21: PLAN.md требует, чтобы возможности лаб 2–3, в том числе bench_restore, работали после каждого change, а 7.2 — задача этого change). switch_api после up --force-recreate сначала ждёт, что процесс каждой новой реплики сам отвечает на /health/ready (Stand.wait_processes_ready: docker exec той же команды, что HEALTHCHECK образа, — только docker CLI), и лишь потом wait_ready. После готовности процесса проверки LB успешны: слот, помеченный DOWN до неё, дождётся снова UP, а не помеченный ведёт на готовый процесс. Альтернатива: ответ через LB с X-Instance-Id нового контейнера — нужен запрос из сети стенда (контейнер k6) на каждое ожидание, а оркестратор управляет только docker CLI. Альтернатива: ждать перехода слота в DOWN — не наступит, если процесс успел подняться до следующей проверки LB, и ожидание зависло бы. Проверка: make bench_restore_quick трижды подряд и --sizes 10000 трижды — код 0; bench_quick, bench_failover_quick, bench_rollout_quick — код 0.

Замечания /opsx:verify 2026-10-21 (задачи группы 10):

  1. Память загрузки — одно тело (W1, решение 6). Проба (scratchpad mem_probe.py) в образе API (Linux, CPython образа), код сервиса — смонтированный src до и после правки: тело PNG 10 449 063 байт блоками по 64 KiB через _read_body, затем _inspect (структура и SHA-256) и то, что botocore делает с bytes (BytesIO и SHA-256 блоками по 1 MiB); три загрузки подряд в одном процессе, пик RSS — VmHWM со сбросом через /proc/self/clear_refs перед каждой, tracemalloc — по стадиям. В долях тела:

    Код Порог mmap glibc RSS: загрузка 1 / 2 / 3 tracemalloc: чтение / проверка / тело PUT
    до (bytearray + bytes(...)) динамический 2,11 / 1,80 / — ¹ 2,10 / 1,02 / 1,20
    после (BytesIO + getvalue()) динамический 1,25 / 2,05 / 1,07 1,11 / 1,02 / 1,20
    до 131072 1,99 / 1,99 / 1,99 —
    после 131072 1,20 / 1,19 / 1,19 —

    ¹ освобождённая куча второй загрузки осталась резидентной, рост 0.

    Без копии getvalue() чтение даёт одно тело, но со вторым запуском glibc поднимает динамический порог mmap до размера освобождённого буфера, буфер растёт в куче, и realloc на миг держит два тела (2,05). Фиксированный порог 128 KiB (MALLOC_MMAP_THRESHOLD_ в Dockerfile) держит буфер в mmap, рост — mremap без копии: 1,00 тела на чтении и 1,19–1,20 с блоками botocore на каждой загрузке. tracemalloc на чтении — 1,11: он считает запас ёмкости BytesIO (до 1/8), страницы запаса не заполняются, RSS их не видит.

  2. «Бомба» — до ожидаемого объёма + 1 байт (W2, решение 2). Блок распаковки ограничивался только 1 MiB, и PNG 100 × 100 с IDAT на 200 MiB распаковывался на 1 048 576 байт при ожидаемых 30 100. max_length = min(1 MiB, ожидаемое − распаковано + 1), выход из цикла — по нему. Проба probe_inflate.py: 30 101 байт, затем DamagedImage. Корпус 11 993 PNG и JPEG системы (выборка 12 000, seed 20261021): вердикт нового модуля совпал с HEAD у всех, ложных отказов против Pillow 0, только по пикселям — 4.

  3. «Старый образ на новой схеме» (W3, дельта db-migrations): make test и make student_test образа e1161f7 красные с лабой 4 на любой схеме — у него нет вложений. Сценарий переформулирован: проверки, которые прежний образ проходил на прежней схеме, проходят и на новой (запись 201, история 200, без 5xx), доказательство — evidence/rollout/attachments/summary.md.

  4. filename не в UTF-8 — 400 (S3, решение 10). Starlette декодирует процент-коды с заменой неверных байтов на U+FFFD, и a%FFb.png давал 201. Ручка до вызова сервиса разбирает scope["query_string"] сама (те же пары, что parse_qsl) и отвечает InvalidFilename (400) на неверный UTF-8 и байт вне ASCII; для принятых значений результат совпадает со Starlette. Порядок проверок прежний: 400 параметров до 404 членства. Новый сценарий спека — «Имя не в UTF-8», тест test_filename_not_utf8.

  5. «Окружение не меняет лимит» (S4, дельта service-configuration): обычный API стенда отказов запускается с MAX_UPLOAD_BYTES=1 и MAX_IMAGE_PIXELS=1, тест fault сверяет, что стенд запущен с ними (FAULT_LIMITS_ENV), и грузит sample.png — 201.

  6. Невидимость pending через API (S6) по HTTP не вызвать без строки pending на стенде отказов: проверка — в upload-consistency (действие hook с id последней pending, PLAN.md).

Open Questions

  • Текст из одних пробелов вместе с вложением — закрыт 2026-10-20 ответом преподавателя: 201 с вложением, 400 без (решение 8).
  • Что API отвечает, когда у строки ready нет объекта или он другого размера: сейчас 500 и error в журнале (решение 7). Пометку таких строк и ответ после неё решит reconciler трека 2. Спеки этого change это не меняет.
  • Срок PUT большого объекта под одновременной записью: отдельный срок по размеру или общий [s3] timeout_seconds. Решит upload-memory по замеру.