Files
mtusi2026lab4/openspec/changes/attachments/design.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

817 lines
59 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.
# 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 до тела;
- чтение в `bytearray` со счётчиком: больше лимита — 413 сразу, без
дочитывания;
- затем один `bytes(...)`.
- Пик памяти загрузки — около двух тел (буфер и копия), пока не
отработал PUT. botocore считает CRC32 потоком, без копии. Сколько
таких загрузок помещается в 512 МБ и чем их ограничить —
`upload-memory`.
- `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`.
- [Память загрузки ~2 × тело без лимита конкурентности: около 30
одновременных загрузок по 10 MiB доводят реплику 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` слота (`KNOWN_ISSUES.md`).
## Open Questions
- ~~Текст из одних пробелов вместе с вложением~~ — закрыт 2026-10-20
ответом преподавателя: 201 с вложением, 400 без (решение 8).
- Что API отвечает, когда у строки `ready` нет объекта или он другого
размера: сейчас 500 и `error` в журнале (решение 7). Пометку таких
строк и ответ после неё решит reconciler трека 2. Спеки этого change
это не меняет.
- Срок PUT большого объекта под одновременной записью: отдельный срок по
размеру или общий `[s3] timeout_seconds`. Решит `upload-memory` по
замеру.