docs: propose attachments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-20 23:44:50 +03:00
co-authored by Claude Opus 5.5
parent e1161f7e6b
commit 73779f7acd
15 changed files with 2623 additions and 0 deletions
+118
View File
@@ -603,3 +603,121 @@ design) и «Вопросы» (ждут ответа; ответ дописыв
разрушающего решения (удалить строку, пометить вложение потерянным)
без проверки, что bucket на месте. Это учитывают `upload-consistency`
и reconciler трека 2.
### attachments
#### Решения
Приняты 2026-10-20 в `/opsx:propose`, подробности — design change
`attachments`.
1. **Строка `pending` до PUT — уже здесь** (решение 1). Порядок:
проверки → `pending` с ключом объекта (commit) → PUT → `ready`
(commit) → 201. При отказе S3 или БД после шага `pending` — 503,
строка остаётся. `upload-consistency` добавит компенсацию, уборщик и
тесты отказов посреди загрузки, порядок шагов не меняя.
2. **Проверка изображения — структура без декодирования** (решение 2),
своя функция на stdlib:
- PNG: CRC чанков, поток IDAT распаковывается ровно в объём по
размерам, типы фильтров строк;
- JPEG: маркеры, один кадр, скан, EOI;
- пиксели — из заголовка до распаковки.
Проба: 12 000 настоящих файлов без ложных отказов, память проверки
до 3,5 MiB, «бомба» отсекается за доли миллисекунды. Pillow — только
dev-группа, для JPEG в тестах. Поведение для клиента подтвердил
пользователь («Вопросы», п. 1).
3. **Схема** (решение 3):
- таблицы `attachments` и `message_attachments` — порядок
`position`, FK без каскада: вложение со ссылкой из сообщения БД
удалить не даст;
- ограничение текста сообщения ослаблено до 0–4000 с `NOT VALID`,
без скана `messages` под эксклюзивной блокировкой (дельта
`db-migrations`);
- чат вложения = чат сообщения проверяет сервис в той же транзакции.
Отвергнуты массив id в `messages`, составной FK с третьим индексом
на `messages` и тип `ENUM`.
4. **Ключ объекта** — `<база>/attachments/<id>/original`, хранится в
`object_key` (уникальный) (решение 4).
5. **Загрузка и скачивание не держат сессию БД** (решение 5). Найдено:
`get_db_session` держит соединение пула и срок 6 с до конца отправки
ответа, и передача 10 MiB медленному клиенту оборвалась бы на 6-й
секунде. Поэтому:
- `db_session_scope()` на каждый шаг с БД;
- вход `CurrentUserBrief` с короткой сессией;
- `AttachmentService(db_scope, cache, storage)`.
6. **Ответы до чтения тела** (решение 6, проба). Ранние 404, 413 и 415
получают httpx, curl и любой клиент через LB. `urllib` напрямую к
одной реплике ответ теряет — ограничение в `REPORT.md`. Медленные
10 MiB через LB проходят: таймауты HAProxy — простой, а не длительность.
7. **Порядок проверок загрузки**: 401 → 400 → 404 → 415 (`Content-Type`)
→ 413 (`Content-Length`) → тело (спек «Порядок проверок загрузки»).
8. **Скачивание** (решение 7):
- поток из S3, отказ S3 — 503 до заголовков;
- заголовок `X-Content-Type-Options: nosniff`;
- `variant` кроме `original` — 400 по перечислению контракта лабы 4;
- строка `ready` без объекта или с другим размером — 500 и `error`
в журнале, строка не меняется.
9. **Хэш идемпотентности** (решение 9): пустой `attachment_ids` хэш не
меняет, id в нижнем регистре, порядок значим.
10. **Лимиты 10 MiB и 40 млн пикселей — константы, не настройки**
(дельта `service-configuration`), соответствие `MAX_UPLOAD_BYTES` и
`MAX_IMAGE_PIXELS` — в `REPORT.md`.
11. **`rollout_from = e1161f7`** — последний commit лабы 4 до этого
change (решение 14). Проверка commit до стенда, правило — в
`bench.md`, запись в `KNOWN_ISSUES.md` удаляется в apply.
12. **Дельты синхронизируются в основные спеки в apply**, как `health`
в `s3-storage`: сверка покрытия читает только `openspec/specs/`.
13. **Проверки отказов вложений** — через hook стенда отказов: счётчики
вложений по статусам и объектов в bucket (решение 12).
#### Вопросы
1. Что считать «повреждённым изображением» (решение 2, спек
`attachments`, «Повреждённое изображение»)? По умолчанию —
структурная проверка без декодирования пикселей:
- 415 — обрезанный файл, битая CRC, сломанные маркеры, поток zlib не
того объёма, «бомба»;
- байты после IEND или EOI принимаются как часть оригинала;
- изменённый байт внутри данных скана JPEG не ловится. У формата нет
контрольной суммы, Pillow его тоже не ловит.
Альтернатива — полное декодирование Pillow. Оно стоит до 160 МБ на
загрузку при лимите реплики 512 МБ, требует семафора уже в этом
change и ловит не больше.
**Ответ пользователя 2026-10-20:** структурная проверка, как по
умолчанию. Менять ничего не нужно.
2. Текст из одних пробелов вместе с вложением. По умолчанию — 400: общее
правило контракта «обязательные строки не состоят только из
пробельных символов», а исключение названо только для `text=""`.
Фраза «нельзя пустой/пробельный текст без вложений» допускает и
прочтение «с вложением можно». Это две трактовки контракта, то есть
вопрос преподавателю (AGENTS.md).
**Ответ пользователя 2026-10-20:** пока 400, как по умолчанию. Это
неоднозначность контракта: `contracts/README.md`, строка 18 («нельзя
… пробельный текст без вложений») против строк 9 (обязательные строки
не из одних пробелов) и 50 (исключение — только `text=""` с
вложением). Пользователь спросит преподавателя.
**Открыт — вопрос преподавателю.** Трактовка временная (design change
`attachments`, решение 8). Ответ записать в AGENTS.md, «Согласования с
преподавателем». Если он другой, поправить валидатор `CreateMessage`,
сценарий `messages` «Пробелы с вложением» и его тест. До ответа
трактовка названа в `REPORT.md` как открытый вопрос.
3. Опасный `filename`. Контракт называет `/`, `\`, NUL и управляющие
символы. По умолчанию 400 и на символы управления направлением
текста (U+202A–U+202E, U+2066–U+2069) и разделители строк (U+2028,
U+2029): ими подменяют видимое имя (например, U+202E перед
`gnp.exe`). ZWJ и остальные форматирующие разрешены: на них держатся
emoji и письменности. Оставить так?
**Ответ пользователя 2026-10-20:** нет, только то, что в контракте:
400 на `/`, `\`, NUL и управляющие символы — категория Unicode Cc
(U+0000–U+001F, U+007F–U+009F). Символы направления текста,
разделители строк U+2028 и U+2029 и прочие символы категорий Cf, Zl и
Zp принимаются и возвращаются без изменений. Спеки `attachments`,
design (решения 3 и 10) и tasks приведены к этому, отвергнутый вариант
с причиной — в design, решение 10.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-20
+774
View File
@@ -0,0 +1,774 @@
# 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; текст пустой без вложений или из одних пробелов (непустой) —
400 (спек `messages`, «Валидация текста»).
**Трактовка временная — до ответа преподавателя** (`PLAN.md`,
`### attachments` → «Вопросы», п. 2). Текст из одних пробелов вместе с
вложением даёт 400: общее правило контракта (`contracts/README.md`,
строка 9) и исключение только для `text=""` (строка 50). Строка 18
(«нельзя … пробельный текст без вложений») допускает и прочтение «с
вложением можно». Ответ преподавателя пойдёт в AGENTS.md,
«Согласования с преподавателем». Если он другой, меняются условие
валидатора, сценарий `messages` «Пробелы с вложением» и его тест.
Остальное решение от этого не зависит.
- `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` напрямую,
смешанные версии при замене;
- открытый вопрос преподавателю: текст из одних пробелов с вложением —
пока 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 и снова видны после
возврата вперёд.
## Open Questions
- Текст из одних пробелов вместе с вложением: ответ преподавателя на
неоднозначность контракта (решение 8, `PLAN.md`, «Вопросы», п. 2).
Пользователь отложил вопрос сам: до ответа — 400. Другой ответ меняет
один сценарий `messages`, условие валидатора и тест отдельной правкой.
Порядок работ от него не зависит.
- Что API отвечает, когда у строки `ready` нет объекта или он другого
размера: сейчас 500 и `error` в журнале (решение 7). Пометку таких
строк и ответ после неё решит reconciler трека 2. Спеки этого change
это не меняет.
- Срок PUT большого объекта под одновременной записью: отдельный срок по
размеру или общий `[s3] timeout_seconds`. Решит `upload-memory` по
замеру.
+140
View File
@@ -0,0 +1,140 @@
# Proposal
## Why
Рубрика «3» лабы 4 почти целиком про вложения (`README.md`): метаданные
в PostgreSQL, байты в приватном bucket, `201 ready` после сохранения,
побайтный download только участникам, `attachment_ids` в сообщении,
реальные PNG/JPEG с лимитами до чтения и распаковки, файл переживает
остановку принявшей его реплики и рестарт стенда. Рубрика «4» требует
негативных тестов: большой файл, повреждённое изображение, подмена MIME,
чужое `attachment_id`, вложение другого чата, ни одной пользовательской
ошибки в 500. Хранилище и клиент S3 готовы (change `s3-storage`), а
домена вложений нет.
Без него красные публичные `make test`, `make test-persistence` и
`make test-failover` (с `LAB=4` они загружают файл) и 32 теста `make
student_test` (контракт лабы 4 требует `attachment_ids` в `Message`). Сверка
покрытия красная, пока четыре файла исключений не сняты на стенде лабы 4.
## What Changes
- Домен `attachment` во всех слоях и три ручки контракта:
- `POST /api/v1/chats/{chat_id}/attachments?filename=…` — сырые байты
PNG/JPEG, `201 Attachment` со `status=ready`;
- `GET /api/v1/attachments/{id}` — метаданные;
- `GET /api/v1/attachments/{id}/content` — оригинал потоком из S3, с
истинным `Content-Type`, без redirect.
- Проверки загрузки до чтения и распаковки:
- `Content-Length` больше 10 MiB — 413 до чтения тела, без него —
счётчик байтов при чтении;
- тип — по сигнатуре содержимого, расхождение с `Content-Type` — 415;
- число пикселей — из заголовка изображения до распаковки, больше
40 млн — 413;
- целостность — структурная проверка без декодирования пикселей.
Память проверки не зависит от числа пикселей, «бомба» отсекается по
заявленному размеру;
- опасный `filename` — 400.
- Порядок записи: проверка → строка `pending` с ключом объекта (commit)
→ PUT в S3 → строка `ready` (commit) → 201. Объект, записанный API,
известен БД до записи. Компенсация и уборщик зависших `pending` — change
`upload-consistency`.
- Ключ объекта назначает сервер: `<имя базы>/attachments/<id>/original`.
`filename` только отображается и ни в ключ, ни в путь не попадает.
- Загрузка и скачивание не держат соединение пула PostgreSQL на время
передачи тела. Короткие транзакции открываются только на шаги с БД.
- Сообщение принимает `attachment_ids` (0–10 уникальных). Каждое
вложение должно быть готовым вложением этого чата, иначе 404.
`text=""` допустим только с вложением. Сообщение, история и повтор по
ключу отдают `attachment_ids` в исходном порядке.
- Хэш тела для идемпотентности учитывает `attachment_ids`, пустой список
его не меняет (`PLAN.md`, решение 6).
- Миграция только расширяет схему: таблицы `attachments` и
`message_attachments`, ограничение длины текста сообщения ослаблено
до 0–4000.
- Отказ S3 — 503 только на путях вложений. Метаданные, текстовые
сообщения и `/health/ready` работают.
- `student-tests/test_attachments.py`: рубрика «4» и все сценарии нового
спека. Новые проверки отказов: S3 остановлен и заморожен при загрузке
и скачивании.
- Драйвер скилла `run-mtusi-messenger`: `upload`, `download` с SHA-256 и
сценарий `attachment-failover` — остановить реплику, принявшую файл, и
скачать его через другую. `flow` загружает и скачивает вложение.
- Профиль `rollout` стенда `bench/` стартует с commit лабы 4 до этого
change (`e1161f7`), а не с commit лабы 3 (`KNOWN_ISSUES.md`). Правило
выбора commit — в `bench.md`. Evidence замены — со старого образа на
схему с вложениями.
- Evidence: `evidence/attachments/`; четыре файла исключений сверки
переснимаются на стенде лабы 4; `evidence/tests/` — зелёные прогоны.
Не входит:
- компенсация, уборщик и тесты отказов посреди загрузки —
`upload-consistency`;
- лимит одновременных загрузок, сроки чтения тела и профиль `uploads` —
`upload-memory`;
- reconciler — трек 2;
- presigned upload, lab5 (202, превью).
## Capabilities
### New Capabilities
- `attachments`: вложения-изображения — загрузка с лимитами до чтения и
распаковки, тип по содержимому, целостность, `filename`, доступ
только участникам, метаданные, побайтный download, где лежат байты и
метаданные, порядок записи, отказ S3, доступность через любую реплику
и после рестарта.
### Modified Capabilities
- `api-conventions`: пары 413 — `payload_too_large` и 415 —
`unsupported_media_type`; строгий UUID на входе и для
`attachment_id` в пути и `attachment_ids` в теле.
- `messages`: `attachment_ids` в отправке, ответе и истории; пустой
текст с вложением; проверка вложений сообщения.
- `idempotency`: тело включает `attachment_ids`. Отсутствующее поле
равно `[]`, порядок значим, повтор отдаёт те же вложения.
- `data-storage`: метаданные вложений и связи с сообщениями — в
PostgreSQL, байты — не в БД; целостность связей в БД; вложения
переживают рестарт.
- `db-migrations`: ослабление ограничения — допустимое расширение
схемы, без скана таблицы под эксклюзивной блокировкой.
- `service-logging`: имя файла и байты вложений не пишутся в журнал.
- `service-configuration`: лимиты вложений — константы контракта, а не
настройки; соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` — в
`REPORT.md`.
- `student-tests`: сверка покрытия включает `attachments`; тесты рубрики
«4» лабы 4; проверки отказов S3 на путях вложений.
- `load-benchmark`: прежний commit профиля замены — commit текущей лабы,
без него отказ до стенда.
## Impact
- Код:
- `src/api/routers/v1/attachment.py`, `src/api/schemas/attachment.py`;
`message.py` в API, сервисе, repo и DTO; `dependencies.py` — сессия
БД на шаг и вход без удержания сессии; `errors.py` — 413 и 415;
- `src/core/services/attachment.py`, `src/core/repos/attachment.py`,
`attachment_object.py` (ключ и объект в S3),
`src/core/exceptions/attachment.py`;
- `src/schemas/` — DTO и enum вложений; `src/utils/image.py` —
структурная проверка PNG/JPEG (только stdlib);
`src/utils/constants.py` — лимиты контракта;
- модели `src/infra/db/models/attachment.py`, ревизия alembic.
- Зависимости: `pillow` только в dev-группе — генерация JPEG в тестах. В
образ и в приложение не входит.
- Тесты: `student-tests/test_attachments.py`, `test_failures.py`,
`api_client.py`, `contract.py`, `spec_coverage.py`, `fault_hook.py`.
- Стенды:
- `bench/run.py` (`rollout_from`);
- регресс `make bench_quick` (запрос истории изменился) и быстрых
профилей `failover`, `rollout`, `restore`.
- Документы:
- правила `api-contract.md`, `api-layer.md`, `service-layer.md`,
`repo-layer.md`, `dto.md`, `migrations.md`, `logging.md`,
`student-tests.md`, `bench.md`, `settings.md`;
- `AGENTS.md` и скилл `run-mtusi-messenger`;
- `REPORT.md` — вложения, порядок записи, ответы на вопросы защиты,
соответствие `MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS`;
- `KNOWN_ISSUES.md` — запись о `rollout_from` закрывается;
- `PLAN.md`.
@@ -0,0 +1,88 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Соответствие статусов и кодов ошибок
Сервис SHALL использовать пары статус — `code`: 400 —
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
`conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`,
500 — `internal_error`, 503 — `unavailable`. Метод, не поддерживаемый
путём, SHALL давать 405 с `code` `invalid_request`.
#### Scenario: Неизвестный путь
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
#### Scenario: Неподдерживаемый метод
- **WHEN** клиент выполняет `DELETE /api/v1/users`
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
#### Scenario: Лимит и тип вложения
- **WHEN** участник загружает вложение больше 10 MiB, а затем текст с
`Content-Type: image/png`
- **THEN** ответы 413 с `code` `payload_too_large` и 415 с `code`
`unsupported_media_type` в формате ошибки
### Requirement: UUID на входе
Идентификатор, который передаёт клиент, SHALL приниматься только как
строка UUID в записи 8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`),
как `format: uuid` контракта. Это `chat_id` и с лабы 4
`attachment_id` в пути, элементы `member_ids` и с лабы 4 элементы
`attachment_ids` в теле. Шестнадцатеричные цифры SHALL приниматься в
любом регистре: UUID в верхнем регистре обозначает тот же
идентификатор, что в нижнем. В ответах идентификаторы остаются в нижнем
регистре (требование «Представление времени и идентификаторов»).
Значение другого типа (массив, объект, число, логическое значение, null)
и строка в другой записи (без дефисов, с префиксом `urn:uuid:`, в
фигурных скобках, с пробелами) SHALL давать 400 `invalid_request`, а не
500 и не успешный ответ. Такой запрос MUST NOT создавать объектов.
#### Scenario: UUID другого типа в теле
- **WHEN** Алиса создаёт чат, где `member_ids` содержит её id и ещё один
элемент — `[]`, `{}`, `123` или `false`
- **THEN** ответ 400 с `code` `invalid_request`, чат не появился в
списке чатов Алисы
#### Scenario: Не UUID в пути
- **WHEN** пользователь с действующей сессией запрашивает чат, историю
чата или отправляет сообщение с верным `Idempotency-Key`, а `chat_id`
в пути равен `123`, `false`, `[]` или `{}`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Другая запись UUID
- **WHEN** участник передаёт id своего чата в пути или Алиса передаёт id
Боба в `member_ids`, записанный без дефисов, с префиксом `urn:uuid:`
или в фигурных скобках
- **THEN** ответ 400 с `code` `invalid_request`; ни чата, ни сообщения
не создано
#### Scenario: UUID в верхнем регистре в пути
- **WHEN** участник запрашивает свой чат, его историю и отправляет в
него сообщение, записав `chat_id` в верхнем регистре
- **THEN** ответы те же, что для `chat_id` в нижнем регистре, а
`id` и `chat_id` в них — в нижнем регистре
#### Scenario: Идентификаторы вложений в другой записи
- **WHEN** участник запрашивает метаданные и байты вложения, записав
`attachment_id` без дефисов, с префиксом `urn:uuid:` или в фигурных
скобках, и отправляет сообщение с таким элементом в `attachment_ids`
- **THEN** каждый ответ 400 с `code` `invalid_request`, сообщение не
создано
#### Scenario: Идентификаторы вложений в верхнем регистре
- **WHEN** участник запрашивает метаданные и байты вложения и
отправляет сообщение с ним, записав id вложения в верхнем регистре
- **THEN** ответы те же, что для id в нижнем регистре, а `id` и
`attachment_ids` в них — в нижнем регистре
@@ -0,0 +1,456 @@
# Spec Delta
## Purpose
Вложения-изображения в чатах с лабы 4. Здесь описано:
- загрузка PNG и JPEG с лимитами до чтения и распаковки;
- проверка типа и целостности по содержимому, правила `filename`;
- доступ только участникам чата, метаданные и побайтный download;
- где лежат метаданные и байты, порядок записи и отказ S3;
- доступность файла через любую реплику и после рестарта стенда.
## ADDED Requirements
### Requirement: Загрузка вложения
`POST /api/v1/chats/{chat_id}/attachments?filename=<имя>` SHALL
принимать тело — сырые байты одного изображения PNG или JPEG, не
multipart и не JSON, с `Content-Type: image/png` или `image/jpeg`. При
успехе ответ SHALL быть 201 с объектом `Attachment` без других полей:
- `id` — новый UUID, его назначает сервер;
- `chat_id` — чат из пути, `owner_id` — текущий пользователь;
- `filename` — переданное имя без изменений;
- `content_type` — тип, определённый по содержимому;
- `size_bytes` и `sha256` (64 шестнадцатеричных символа в нижнем
регистре) — размер и SHA-256 принятых байтов;
- `status` — `ready`, `variants` — `[]`, `error_code` — null;
- `created_at` и `updated_at` — время сервера в RFC 3339 UTC.
Ответ 201 SHALL означать, что сохранены и оригинал, и метаданные
(требование «Порядок записи»). Загрузку может выполнить любой участник
чата.
#### Scenario: Загрузка PNG
- **WHEN** Алиса загружает в свой чат публичный fixture
`tests/fixtures/sample.png` с `Content-Type: image/png` и
`filename=sample.png`
- **THEN** ответ 201, `status` `ready`, `variants` `[]`, `error_code`
null, `owner_id` — Алиса, `chat_id` — этот чат, `filename`
`sample.png`, `content_type` `image/png`, `size_bytes` 111817, а
`sha256` равен SHA-256 файла
#### Scenario: Загрузка JPEG
- **WHEN** Боб загружает в общий с Алисой чат настоящий JPEG с
`Content-Type: image/jpeg`
- **THEN** ответ 201, `content_type` `image/jpeg`, `owner_id` — Боб, а
`size_bytes` и `sha256` совпадают с размером и SHA-256 файла
#### Scenario: Разновидности PNG и JPEG
- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, в
оттенках серого с альфа-каналом, 16 и 1 бит на канал, чересстрочный
(Adam7), а также JPEG прогрессивный, в оттенках серого, CMYK и с EXIF
- **THEN** каждый ответ 201 с `content_type` по формату файла
### Requirement: Лимит размера до чтения тела
Тело больше 10 485 760 байт (10 MiB) SHALL отклоняться ответом 413
`payload_too_large`, а тело ровно 10 485 760 байт проверку размера
SHALL проходить. Если `Content-Length` запроса больше лимита, ответ
SHALL отдаваться без чтения тела. Без `Content-Length` (передача
частями) тело SHALL читаться потоком со счётчиком. Ответ 413 SHALL
отдаваться, как только прочитано больше лимита, остаток тела MUST NOT
читаться. На одну загрузку процесс API MUST NOT держать в памяти больше
лимита и одного блока чтения тела.
#### Scenario: Граница размера
- **WHEN** участник загружает настоящий PNG размером ровно 10 485 760
байт, а затем такой же PNG на один байт длиннее
- **THEN** первый ответ 201, второй — 413 `payload_too_large`
#### Scenario: Заявленный размер больше лимита
- **WHEN** участник загружает 30 MiB с `Content-Length` 31 457 280
- **THEN** ответ 413 `payload_too_large` в формате ошибки, а клиент
получает его, не дожидаясь отправки всего тела
#### Scenario: Большое тело без Content-Length
- **WHEN** участник передаёт 30 MiB частями, без `Content-Length`
- **THEN** ответ 413 `payload_too_large` в формате ошибки
### Requirement: Лимит пикселей до распаковки
Ширину и высоту изображения сервис SHALL брать из заголовка до
распаковки данных: у PNG — из IHDR, у JPEG — из маркера кадра. Больше
40 000 000 пикселей — ответ 413 `payload_too_large`, ровно 40 000 000
проверку SHALL проходить. Проверка MUST NOT декодировать изображение в
память процесса API: распакованные данные PNG SHALL проверяться
потоком, их объём MUST NOT превышать следующего из размеров
изображения, и память проверки не зависит от числа пикселей. Данные
длиннее заявленных размеров — повреждённое изображение (требование
«Повреждённое изображение»).
#### Scenario: Огромные размеры в маленьком файле
- **WHEN** участник загружает PNG и JPEG по несколько килобайт, в
заголовке которых 40 000 001 пиксель и больше
- **THEN** каждый ответ 413 `payload_too_large`
#### Scenario: Ровно 40 млн пикселей
- **WHEN** участник загружает настоящий PNG 8000 × 5000 пикселей
- **THEN** ответ 201
#### Scenario: Данные длиннее размеров
- **WHEN** участник загружает PNG 100 × 100, данные изображения
которого распаковываются в сотни мегабайт
- **THEN** ответ 415 `unsupported_media_type`, а сервис не
распаковывает данные дальше заявленного размера изображения
### Requirement: Тип по содержимому
Тип вложения SHALL определяться по первым байтам содержимого: сигнатура
PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ SHALL быть
415 `unsupported_media_type`, если:
- `Content-Type` запроса нет или его тип не `image/png` и не
`image/jpeg`; параметры типа и регистр букв не учитываются;
- содержимое не PNG и не JPEG, в том числе пустое тело;
- тип содержимого не совпадает с `Content-Type` запроса (подмена MIME).
#### Scenario: Не изображение
- **WHEN** участник загружает текст, тело GIF и пустое тело с
`Content-Type: image/png`
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Подмена MIME
- **WHEN** участник загружает настоящий JPEG с `Content-Type: image/png`
и настоящий PNG с `Content-Type: image/jpeg`
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Неподходящий Content-Type
- **WHEN** участник загружает настоящий PNG с `Content-Type`
`application/octet-stream`, `text/plain` и без `Content-Type`, а затем
с `Content-Type: IMAGE/PNG; charset=binary`
- **THEN** первые три ответа 415, последний — 201
### Requirement: Повреждённое изображение
Сервис SHALL проверять целостность структуры изображения без
декодирования пикселей и отвечать 415 `unsupported_media_type` на
заведомо повреждённое.
- PNG:
- первым идёт IHDR с допустимыми полями;
- каждый чанк целиком в файле, и его CRC верна;
- неизвестных критичных чанков нет;
- данные изображения (IDAT) идут подряд, их поток zlib завершён и
распаковывается ровно в объём, который следует из размеров, глубины
цвета и чересстрочности;
- тип фильтра каждой строки допустим;
- IEND есть.
- JPEG:
- маркеры и длины сегментов разбираются до конца;
- кадр (SOF) один и с ненулевыми размерами;
- есть хотя бы один скан;
- есть маркер конца EOI.
Байты после IEND или EOI повреждением не считаются: они входят в
оригинал, в его размер и SHA-256. Искажения внутри сжатых данных
скана JPEG, которые не нарушают структуру, сервис не обнаруживает: у
формата нет контрольной суммы.
#### Scenario: Обрезанный файл
- **WHEN** участник загружает PNG и JPEG, обрезанные наполовину и без
последних байтов
- **THEN** каждый ответ 415 `unsupported_media_type`
#### Scenario: Испорченные данные PNG
- **WHEN** участник загружает `sample.png` с одним изменённым байтом
внутри IDAT и сигнатуру PNG, за которой случайные байты
- **THEN** оба ответа 415 `unsupported_media_type`
#### Scenario: Хвост после конца изображения
- **WHEN** участник загружает PNG и JPEG, к которым дописаны байты
после IEND и EOI
- **THEN** оба ответа 201, `size_bytes` и `sha256` учитывают дописанные
байты, а скачанный оригинал содержит их
### Requirement: Имя файла
`filename` SHALL содержать от 1 до 255 Unicode code points. Ответ SHALL
быть 400 `invalid_request`, если параметра нет, имя пустое, длиннее
255 code points, состоит из одних пробельных символов или содержит:
- `/` или `\`;
- управляющий символ — категория Unicode Cc: U+0000–U+001F, в том числе
NUL, или U+007F–U+009F.
Отказ ограничен этим списком контракта (`contracts/README.md`). Прочие
символы SHALL приниматься, в том числе:
- символы форматирования и управления направлением текста (категория
Cf, например U+202E и U+2066);
- разделители строк и абзацев U+2028 и U+2029.
Принятое имя SHALL храниться и возвращаться без изменений, без обрезки
и нормализации. Имя только отображается: оно MUST NOT участвовать в
ключе объекта и в пути на диске. Как безопасно показать имя, решает
клиент.
#### Scenario: Опасное имя
- **WHEN** участник загружает настоящий PNG с `filename`
`../x.png`, `a/b.png`, `a\b.png`, с NUL, с переводом строки, с DEL, с
управляющим символом C1 U+0085, пустым, из одних пробелов и из 256
code points
- **THEN** каждый ответ 400 `invalid_request`
#### Scenario: Имя в Unicode
- **WHEN** участник загружает файл с `filename` из 255 code points:
кириллица, emoji с ZWJ и пробелы по краям
- **THEN** ответ 201, а `filename` в ответе загрузки и в метаданных
совпадает с переданным
#### Scenario: Символы форматирования в имени
- **WHEN** участник загружает файлы, в `filename` которых есть U+202E,
U+2066 с U+2069, U+2028 и мягкий перенос U+00AD
- **THEN** каждый ответ 201, а `filename` в ответе загрузки и в
метаданных совпадает с переданным
### Requirement: Порядок проверок загрузки
Если у загрузки несколько ошибок, ответ SHALL определяться первой из
них по порядку:
1. 401 — нет действительной сессии;
2. 400 — неверный `chat_id` или `filename`;
3. 404 — чата нет или пользователь в нём не состоит;
4. 415 — `Content-Type` запроса;
5. 413 — `Content-Length` запроса;
6. 413 — число прочитанных байтов;
7. 415 или 413 — содержимое: формат и целостность или число пикселей.
Тело MUST NOT читаться, пока не пройдены проверки 1–5. Ошибка клиента
MUST NOT давать 500.
#### Scenario: Посторонний с большим файлом
- **WHEN** Ева загружает 30 MiB в чат Алисы и Боба
- **THEN** ответ 404 `not_found`, а не 413
#### Scenario: Без сессии с опасным именем
- **WHEN** загрузка без `Authorization` идёт с `filename` `a/b.png`, а
затем с допустимым именем
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
#### Scenario: Неверный тип и большой размер
- **WHEN** участник загружает 30 MiB с `Content-Type: text/plain`
- **THEN** ответ 415 `unsupported_media_type`
### Requirement: Доступ к вложению
Метаданные и байты вложения SHALL быть доступны любому участнику чата
вложения, а не только владельцу. Посторонний, неизвестный `id` и
вложение, загрузка которого не завершена, SHALL получать одинаковый 404
`not_found`. Запрос без действительной сессии — 401, `attachment_id` не
UUID — 400 `invalid_request`.
#### Scenario: Другой участник
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб запрашивает
его метаданные и байты
- **THEN** оба ответа 200
#### Scenario: Посторонний и неизвестный id
- **WHEN** Ева запрашивает метаданные и байты вложения чата Алисы и
Боба, а Алиса — по случайному UUID
- **THEN** все ответы 404 `not_found` с одинаковым `message`
#### Scenario: Неверный id вложения
- **WHEN** участник запрашивает метаданные и байты по `attachment_id`
`123` и `abc`
- **THEN** каждый ответ 400 `invalid_request`
#### Scenario: Чтение без сессии
- **WHEN** метаданные и байты вложения запрашиваются без
`Authorization`
- **THEN** оба ответа 401 `unauthorized` с `WWW-Authenticate: Bearer`
### Requirement: Метаданные вложения
`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с
объектом `Attachment`, равным ответу на загрузку этого вложения.
#### Scenario: Метаданные равны ответу загрузки
- **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные
- **THEN** ответ 200, JSON совпадает с ответом на загрузку во всех
полях
### Requirement: Скачивание оригинала
`GET /api/v1/attachments/{attachment_id}/content` SHALL отвечать 200 с
байтами оригинала без изменений: их размер и SHA-256 равны `size_bytes`
и `sha256` вложения. Заголовки ответа:
- `Content-Type` — `content_type` вложения без параметров;
- `Content-Length` — размер оригинала;
- `X-Content-Type-Options: nosniff`.
Байты SHALL отдавать API, ответ MUST NOT быть перенаправлением.
Параметр `variant` SHALL принимать только `original`, это и значение по
умолчанию. Любое другое значение — 400 `invalid_request`. Ключ объекта,
адрес и учётные данные S3 MUST NOT попадать ни в тело, ни в заголовки
ответов API.
#### Scenario: Побайтный оригинал
- **WHEN** Боб скачивает PNG и JPEG, загруженные Алисой
- **THEN** каждый ответ 200, не перенаправление, байты совпадают с
загруженными, `Content-Type` — `image/png` и `image/jpeg`,
`Content-Length` равен размеру, есть `X-Content-Type-Options: nosniff`
#### Scenario: Вариант original
- **WHEN** участник скачивает вложение с `variant=original`, а затем с
`variant=thumbnail` и с пустым `variant`
- **THEN** первый ответ 200 с теми же байтами, остальные — 400
`invalid_request`
#### Scenario: Без следов хранилища в ответе
- **WHEN** участник загружает вложение, читает метаданные и скачивает
байты
- **THEN** в телах ответов нет полей вне схемы контракта, а в
заголовках нет `Location` и заголовков `x-amz-*`
### Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты оригинала —
одним объектом в приватном bucket S3 (`object-storage`). Байты MUST
NOT храниться ни в PostgreSQL, ни в файлах реплики API. Ключ объекта
назначает сервер: имя базы, `/attachments/`, `id` вложения и
`/original`. Каждая загрузка SHALL создавать новое вложение и новый
объект, в том числе повтор той же загрузки: прозрачных повторов
загрузки нет (`contracts/README.md`).
#### Scenario: Байты не в БД и не на диске API
- **WHEN** после загрузок через балансировщик проверяющий смотрит
схему таблиц вложений, ключи объектов в PostgreSQL, объекты в bucket
и изменения файловой системы контейнеров реплик API
- **THEN** в таблицах нет колонки с байтами изображения, ключ каждого
объекта имеет вид `<база>/attachments/<id>/original` и не содержит
`filename`, объект с этим ключом есть в bucket, анонимный GET его
ключа — 403, а в контейнерах реплик нет файлов оригиналов
#### Scenario: Повторная загрузка
- **WHEN** участник дважды загружает один и тот же файл
- **THEN** оба ответа 201 с разными `id` и одинаковым `sha256`, и оба
вложения скачиваются
### Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
1. проверки и чтение тела;
2. запись метаданных в статусе «загружается» (`pending`) вместе с
ключом объекта, фиксация в PostgreSQL;
3. запись объекта в S3;
4. статус `ready`, фиксация;
5. ответ 201.
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3. Вложение не в статусе `ready` MUST NOT быть видно через API: его
метаданные и байты — 404, ссылка на него в сообщении — 404. Если не
удались запись в S3 или фиксация `ready`, ответ SHALL быть 503
`unavailable`, строка «загружается» остаётся. Её и объект убирает
уборщик (change `upload-consistency`). Загрузка, отклонённая до шага 2
(401, 400, 404, 413, 415), MUST NOT оставлять ни строки, ни объекта.
#### Scenario: Запись в S3 не удалась
- **WHEN** S3 остановлен, и участник загружает настоящий PNG
- **THEN** ответ 503 `unavailable`, в PostgreSQL на одно вложение в
статусе «загружается» больше, готовых — столько же
- **AND** текстовое сообщение в тот же чат — 201, а после возврата S3
та же загрузка — 201
#### Scenario: Отклонённая загрузка ничего не оставляет
- **WHEN** участник и посторонний отправляют загрузки, которые
отклоняются с 404, 413 по `Content-Length`, 413 по счётчику, 413 по
пикселям, 415 по типу и 415 по целостности
- **THEN** число вложений в PostgreSQL в каждом статусе и число
объектов вложений в bucket не изменились
### Requirement: Недоступность S3
Если S3 недоступен, не ответил за срок вызова или отказал
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
- метаданные вложения;
- история чата с `attachment_ids`;
- отправка сообщений, в том числе со ссылкой на готовое вложение;
- `/health/ready`.
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
API.
#### Scenario: S3 остановлен
- **WHEN** вложение загружено, затем S3 остановлен, и участник
скачивает байты, читает метаданные, отправляет сообщение с этим
вложением и запрашивает `/health/ready`
- **THEN** скачивание — 503 `unavailable`, метаданные — 200, сообщение
— 201, готовность — 200
- **AND** после возврата S3 скачивание — 200 с теми же байтами
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и участник
загружает файл и скачивает байты готового вложения
- **THEN** оба ответа 503 `unavailable` не позже срока вызова S3 с
запасом, а после разморозки скачивание — 200
### Requirement: Вложение доступно через любую реплику
Готовое вложение SHALL скачиваться через любую реплику API за
балансировщиком, в том числе после остановки реплики, которая его
приняла. Метаданные и оригинал SHALL переживать перезапуск стенда
(`scripts/restart.sh`, вместе с S3) с сохранёнными volumes и читаться
прежним токеном.
#### Scenario: Скачивание через другую реплику
- **WHEN** вложение загружено через балансировщик, ответ дала реплика
с одним `X-Instance-Id`
- **THEN** байты скачиваются через реплику с другим `X-Instance-Id` и
совпадают с загруженными
#### Scenario: Принявшая реплика остановлена
- **WHEN** вложение загружено через балансировщик, затем реплика с
`X-Instance-Id` ответа на загрузку остановлена `scripts/stop-one.sh`
- **THEN** метаданные и байты через балансировщик — 200 от другой
реплики, SHA-256 совпадает с загруженным, посторонний получает 404
#### Scenario: Рестарт стенда
- **WHEN** вложение загружено, затем выполнен `scripts/restart.sh`
- **THEN** прежним токеном метаданные — 200, а байты совпадают с
загруженными по SHA-256
@@ -0,0 +1,71 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Хранение в PostgreSQL
Пользователи, чаты, участники чатов, сообщения, сессии, а с лабы 4 —
метаданные вложений и связи сообщений с вложениями SHALL храниться в
PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные
в памяти процесса, файлах или SQLite. Байты вложений SHALL храниться в
S3 (capability `attachments`, `object-storage`), а не в PostgreSQL и не
в файлах реплик. Подтверждённая запись (ответ 201 или 204) SHALL быть
зафиксирована до ответа и видна следующему запросу.
#### Scenario: Созданное видно сразу
- **WHEN** клиент зарегистрировался и следующим запросом входит с теми
же username и паролем
- **THEN** вход успешен, и `GET /api/v1/users/me` с выданным токеном
возвращает этого пользователя
### Requirement: Данные переживают рестарт
После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее
подтверждённые пользователи, чаты, участники и сообщения SHALL быть
доступны в прежнем виде. С лабы 4 это относится и к вложениям: их
метаданные, `attachment_ids` сообщений и оригиналы переживают и
перезапуск S3 с его volume.
#### Scenario: Прежний пользователь после рестарта
- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует
токен, полученный до рестарта
- **THEN** ответ 200, а история чата этого пользователя содержит те же
сообщения в том же порядке
### Requirement: Целостность данных в БД
Ограничения SHALL проверяться самой БД, а не только сервисом:
- уникальность `username`;
- существование пользователей и чатов, на которые ссылаются участники
и сообщения;
- уникальность участника в чате;
- членство отправителя в чате сообщения.
С лабы 4 БД SHALL проверять и вложения:
- владелец вложения — участник его чата;
- связь сообщения с вложением ссылается на существующие сообщение и
вложение;
- вложение не повторяется в одном сообщении, у каждого места в порядке
одно вложение, мест не больше 10;
- вложение, на которое ссылается сообщение, удалить нельзя;
- допустимые значения размера, SHA-256, типа, статуса и длины
`filename`; ключ объекта уникален.
Порядок `member_ids`, заданный при создании чата, и порядок
`attachment_ids` сообщения SHALL сохраняться. Принадлежность вложения
чату сообщения проверяет сервис в той же транзакции: чат вложения и
чат сообщения не меняются после записи.
#### Scenario: Порядок участников
- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]`
- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в
том же порядке, в том числе после рестарта стенда
#### Scenario: Порядок вложений
- **WHEN** сообщение отправлено с `attachment_ids` `[C, A, B]`
- **THEN** ответ на отправку, история чата и повтор с тем же ключом
возвращают `[C, A, B]`
@@ -0,0 +1,68 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Совместимость миграции с работающей версией
Миграция SHALL только расширять схему:
- новая таблица со своими ограничениями и внешними ключами;
- новая колонка, допускающая NULL или со значением по умолчанию;
- новый индекс;
- ослабление ограничения: новое условие пропускает всё, что пропускало
прежнее, поэтому прежняя версия не пишет значений, которые новое
условие запретит.
Ослабленное ограничение SHALL добавляться без проверки существующих
строк под эксклюзивной блокировкой таблицы: эти строки уже
удовлетворяли более строгому условию.
Удаление и переименование таблицы, колонки или ограничения (кроме
замены ограничения ослабленным), а также новое ограничение, которое
нарушит запись прежней версии, MUST NOT входить в ту же поставку, что и
код, которому они нужны. Такое изменение выполняется отдельной миграцией
после того, как реплик прежней версии не осталось (expand/contract).
Если так сделать нельзя, ограничение SHALL описываться в `REPORT.md`.
Реплики прежнего образа SHALL обслуживать обязательные запросы на
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
требовать отката схемы.
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
Долгая транзакция приложения не должна заставить миграцию держать
очередь за собой и остановить запись остальных реплик. Срок SHALL быть
меньше срока запроса приложения к БД (`statement_timeout`): запросы,
вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
проходить.
#### Scenario: Старый образ на новой схеме
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
образа применены, а реплики не заменены
- **THEN** `make test` и `make student_test` через LB проходят на
прежних репликах
#### Scenario: Запись прежней версии
- **WHEN** после новой миграции сообщение отправлено через реплику
прежнего образа
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
образа
#### Scenario: Блокировка не получена
- **WHEN** таблицу, которую меняет миграция, держит открытая
транзакция дольше срока ожидания блокировки
- **THEN** миграция завершается ошибкой, схема не меняется, запросы
других клиентов, ждавшие за миграцией, получают успешный ответ, а
после окончания транзакции повторный запуск применяет миграцию
#### Scenario: Ослабленное ограничение
- **WHEN** миграция вложений заменяет ограничение длины текста
сообщения (было 1–4000, стало 0–4000) на таблице с сообщениями, а
запись идёт через реплики прежнего образа
- **THEN** миграция не проверяет существующие строки, записи прежних
реплик во время и после неё — 201, а после замены реплик сообщение с
пустым текстом и вложением — 201
@@ -0,0 +1,67 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Повтор возвращает исходный результат
Повтор от того же пользователя в тот же чат с тем же ключом и тем же
телом в пределах срока ключа SHALL возвращать 201 и тот же `Message`:
тот же `id`, `text`, `attachment_ids` и `created_at` до микросекунды.
Новое сообщение MUST NOT создаваться. Тела SHALL сравниваться по смыслу,
после разбора JSON. На результат не влияют:
- запись пробелов и экранирование символов;
- порядок полей объекта;
- отсутствующий `attachment_ids` вместо `[]`;
- регистр букв в идентификаторах вложений.
Порядок элементов `attachment_ids` значим: это порядок вложений в
сообщении. Ключ, сохранённый версией сервиса без вложений, SHALL
повторяться тем же телом и после замены реплик на версию с вложениями.
#### Scenario: Повтор того же тела
- **WHEN** Алиса отправляет текст T с ключом K и повторяет тот же
запрос
- **THEN** оба ответа 201 с одинаковым JSON, а в истории чата одно
сообщение с текстом T
#### Scenario: Тот же JSON в другой записи
- **WHEN** повтор с ключом K несёт то же тело в другой записи: с
другими пробелами и с текстом в экранировании `\uXXXX`
- **THEN** ответ 201 с тем же `Message`, новое сообщение не создано
#### Scenario: Вложения по умолчанию
- **WHEN** Алиса отправила `{"text": T}` с ключом K и повторяет с K
тело `{"attachment_ids": [], "text": T}`
- **THEN** ответ 201 с тем же `Message`, новое сообщение не создано
#### Scenario: Повтор сообщения с вложениями
- **WHEN** Алиса отправила текст с `attachment_ids` `[A, B]` и ключом K,
затем повторяет с K то же тело, а потом то же тело с A и B в верхнем
регистре
- **THEN** оба ответа 201 с тем же `Message` и `attachment_ids`
`[A, B]`, в истории одно такое сообщение
### Requirement: Другое тело с тем же ключом
Если ключ в своей области уже использован с другим телом и срок не
истёк, сервис SHALL отвечать 409 `conflict`. Новое сообщение MUST NOT
создаваться, сохранённый результат ключа MUST NOT меняться. Другие
вложения или их другой порядок — другое тело.
#### Scenario: Другой текст
- **WHEN** Алиса отправила T1 с ключом K, затем отправляет T2 с тем же
ключом в тот же чат
- **THEN** второй ответ 409 `conflict`, в истории только T1, а повтор
T1 с K по-прежнему возвращает исходный `Message`
#### Scenario: Другие вложения
- **WHEN** Алиса отправила текст с `attachment_ids` `[A, B]` и ключом
K, затем шлёт с K тот же текст с `[B, A]`, а потом без вложений
- **THEN** оба ответа 409 `conflict`, в истории одно сообщение с
`[A, B]`
@@ -0,0 +1,31 @@
# Spec Delta
## ADDED Requirements
### Requirement: Прежний commit профиля замены
Commit, с образа которого стартуют реплики профилей `rollout` и
`rollout_quick`, SHALL задаваться методикой профиля. Это commit
текущей лабы до изменения, которое показывает замена. Сейчас таким
изменением SHALL быть миграция вложений: commit — последний перед
change `attachments`. Commit SHALL меняться при переходе в следующую
лабу (commit прошлой лабы в её истории нет) и когда замена показывает
новое изменение схемы. Правило и текущее значение SHALL быть в
`.claude/rules/bench.md`, commit — в паспорте метки.
Если commit методики нет в истории репозитория, команда SHALL
завершаться с ненулевым кодом до запуска стенда, назвать commit и
подмену `--from <commit>` для отладки.
#### Scenario: Замена на схему с вложениями
- **WHEN** выполнен `make bench_rollout_quick` на коде с вложениями
- **THEN** реплики стартуют на образе commit до change `attachments`,
ревизия схемы до замены — без таблиц вложений, после — с ними, а
команда завершается с кодом 0
#### Scenario: Commit вне истории
- **WHEN** commit методики не найден в репозитории
- **THEN** команда завершается с ненулевым кодом до запуска стенда, а
сообщение называет commit и `--from`
@@ -0,0 +1,146 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Отправка сообщения
`POST /api/v1/chats/{chat_id}/messages` SHALL принимать тело
`{"text": ..., "attachment_ids": [...]}` с заголовком `Idempotency-Key`.
`attachment_ids` необязателен, по умолчанию `[]`. При успехе ответ SHALL
быть 201 с объектом `Message`: `id`, `chat_id`, `sender_id`, `text`,
`created_at`, `attachment_ids`, без других полей.
- `sender_id` SHALL быть текущим пользователем;
- `text` SHALL совпадать с отправленным;
- `attachment_ids` SHALL совпадать с отправленными, в том же порядке,
без поля в запросе — `[]`.
Формат ключа, повтор и конфликт описаны в capability `idempotency`,
проверка вложений — в требовании «Вложения в сообщении».
#### Scenario: Участник отправляет сообщение
- **WHEN** Алиса отправляет `"Привет, мир 👋"` в свой чат с новым
`Idempotency-Key`
- **THEN** ответ 201, `sender_id` — Алиса, `chat_id` — этот чат, `text`
равен `"Привет, мир 👋"`, `attachment_ids` — `[]`
#### Scenario: Сообщение с вложениями
- **WHEN** Алиса загрузила в чат вложения A и B и отправляет текст с
`attachment_ids` `[B, A]`
- **THEN** ответ 201, `attachment_ids` — `[B, A]`
### Requirement: Валидация текста
`text` SHALL содержать не больше 4000 Unicode code points. Пустая строка
SHALL допускаться только вместе с хотя бы одним вложением. Текст из
одних пробельных символов MUST NOT приниматься ни с вложениями, ни без
них. Поле `sender_id` в теле MUST NOT приниматься. Нарушения SHALL
давать 400 `invalid_request`.
#### Scenario: Пустой текст
- **WHEN** участник отправляет `{"text": ""}`
- **THEN** ответ 400
#### Scenario: Граница длины
- **WHEN** текст из 4000 code points, затем из 4001
- **THEN** первый запрос даёт 201, второй — 400
#### Scenario: Попытка подменить отправителя
- **WHEN** тело содержит `sender_id` другого пользователя
- **THEN** ответ 400, сообщение не создаётся
#### Scenario: Пустой текст с вложением
- **WHEN** участник отправляет `{"text": "", "attachment_ids": [A]}` с
готовым вложением A своего чата
- **THEN** ответ 201, `text` — пустая строка, `attachment_ids` — `[A]`
#### Scenario: Пробелы с вложением
- **WHEN** участник отправляет `{"text": " ", "attachment_ids": [A]}`
- **THEN** ответ 400 `invalid_request`, сообщение не создаётся
### Requirement: История чата
`GET /api/v1/chats/{chat_id}/messages` SHALL возвращать сообщения чата
в порядке `(created_at, id)` по возрастанию, с постраничным выводом по
capability `pagination`. Любой участник SHALL видеть все сообщения
чата, в том числе чужие. Каждое сообщение SHALL содержать
`attachment_ids` в порядке отправки.
#### Scenario: Два участника, две страницы
- **WHEN** Алиса и Боб отправили по сообщению, и Боб читает историю с
`limit=1`, а затем продолжает по курсору
- **THEN** первая страница содержит одно сообщение и непустой
`next_cursor`, вторая — второе сообщение и `next_cursor` null, а
порядок совпадает с `(created_at, id)`
#### Scenario: Вложения в истории
- **WHEN** Алиса отправила сообщение с `attachment_ids` `[B, A]`, а Боб
— текстовое сообщение
- **THEN** в истории у первого `attachment_ids` — `[B, A]`, у второго —
`[]`
## ADDED Requirements
### Requirement: Вложения в сообщении
`attachment_ids` SHALL содержать от 0 до 10 уникальных идентификаторов
в записи UUID (`api-conventions`, «UUID на входе»). Повтор
идентификатора, в том числе в другом регистре букв, больше 10
элементов, элемент не UUID и не массив — 400 `invalid_request`.
Каждое вложение SHALL быть готовым вложением этого чата. Одинаковый 404
`not_found` дают:
- неизвестное вложение;
- вложение другого чата, в том числе чата, где отправитель не состоит;
- вложение, загрузка которого не завершена.
Сообщение при этом MUST NOT создаваться. Сервис SHALL принимать ссылку
на вложение чата от любого его участника, а не только от владельца, и
одно вложение SHALL входить в несколько сообщений. Сообщение и его
связи с вложениями SHALL сохраняться одной транзакцией.
#### Scenario: Вложение другого участника
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб отправляет
сообщение с этим вложением
- **THEN** ответ 201
#### Scenario: Вложение другого чата
- **WHEN** Алиса состоит в чатах X и Y, загрузила вложение в Y и
отправляет в X сообщение с ним
- **THEN** ответ 404 `not_found`, в истории X нового сообщения нет
#### Scenario: Чужое вложение
- **WHEN** Ева загрузила вложение в свой чат, а Алиса отправляет в свой
чат сообщение с ним
- **THEN** ответ 404 `not_found`, сообщение не создано
#### Scenario: Неизвестное вложение
- **WHEN** участник отправляет сообщение со случайным UUID в
`attachment_ids`
- **THEN** ответ 404 `not_found`, сообщение не создано
#### Scenario: Неверный список вложений
- **WHEN** участник отправляет `attachment_ids` с повтором одного
вложения, с тем же вложением в верхнем регистре, из 11 элементов,
строкой вместо массива и с элементом `123`
- **THEN** каждый ответ 400 `invalid_request`, сообщений не создано
#### Scenario: Одно вложение в двух сообщениях
- **WHEN** участник дважды отправляет сообщение с одним и тем же
вложением
- **THEN** оба ответа 201, у обоих сообщений это вложение в
`attachment_ids`
@@ -0,0 +1,18 @@
# Spec Delta
## ADDED Requirements
### Requirement: Лимиты вложений — константы контракта
Лимиты вложения — 10 485 760 байт на тело и 40 000 000 пикселей — SHALL
быть константами приложения, а не настройками: их задаёт контракт, и
они одинаковы на всех установках. Ни окружение, ни `.env`, ни
`config.toml` MUST NOT их менять. Соответствие имён skeleton
`MAX_UPLOAD_BYTES` и `MAX_IMAGE_PIXELS` этим константам SHALL быть
описано в `REPORT.md`.
#### Scenario: Окружение не меняет лимит
- **WHEN** сервис запущен с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`
в окружении, и участник загружает `sample.png`
- **THEN** ответ 201: лимиты остались контрактными
@@ -0,0 +1,65 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Без содержимого сообщений и личных данных
Записи MUST NOT содержать текст сообщений, `display_name`, названия
чатов, значения `username`, тела запросов и ответов. Записи MUST NOT
содержать пароли, токены сессий, их хэши, значение заголовка
`Authorization`, значение `Idempotency-Key` и параметры SQL-запросов.
Для сообщений допускаются идентификаторы и длина текста. Повтор
отправки SHALL быть виден по признаку повтора и `id` сообщения. Для
сессий допускаются `id` сессии и `user_id`.
С лабы 4 записи MUST NOT содержать:
- ключи доступа и секретные ключи S3;
- ключ подписи служебных вызовов S3;
- подписи запросов к S3: их заголовок `Authorization` и параметры
подписи;
- байты объектов;
- `filename` вложений.
Для обращений к S3 допускаются адрес S3, имя bucket, ключ объекта,
размер, длительность и класс ошибки. Для вложений допускаются `id`
вложения и чата, размер, тип, ширина и высота изображения, длина
`filename` и причина отказа в загрузке.
#### Scenario: Отправка сообщения
- **WHEN** участник отправляет сообщение с текстом T
- **THEN** ни одна запись журнала не содержит T, а запись о создании
сообщения содержит его `id`, `chat_id` и длину текста
#### Scenario: Повтор с ключом
- **WHEN** участник отправляет сообщение с ключом K, повторяет запрос,
а затем шлёт с K другое тело
- **THEN** ни одна запись журнала не содержит K; запись о повторе
содержит `id` исходного сообщения и признак повтора, а ответ 409
виден в итоговой записи запроса
#### Scenario: Вход и выход
- **WHEN** пользователь регистрируется с паролем P, входит, получает
токен T и выходит, а затем кто-то пытается войти с неверным паролем
- **THEN** ни одна запись журнала не содержит P, T, хэш T и значение
`Authorization`; записи о создании и отзыве сессии содержат `user_id`
и `id` сессии, а неудачный вход записан с уровнем `warning` без
username и пароля
#### Scenario: Обращение к S3
- **WHEN** сервис стартует, затем обращается к S3 сначала с верным, а
потом с неверным секретом API
- **THEN** ни одна запись журнала не содержит ключ доступа, секрет и
подпись запроса; запись о старте содержит адрес S3 и имя bucket, а
отказ в учётных данных записан с уровнем `error`
#### Scenario: Загрузка вложения
- **WHEN** участник загружает изображение с уникальным `filename` F, а
затем повреждённый файл с тем же именем
- **THEN** ни одна запись журнала не содержит F; запись о загрузке
содержит `id` вложения, размер и тип, а запись об отказе — причину
отказа без имени файла
@@ -0,0 +1,234 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Обязательные сценарии рубрики
Набор SHALL содержать отдельные тесты для сценариев уровня «4»:
неверный JSON, чужой чат, пустое сообщение, дубликат `username`, обход
нескольких страниц истории, а с лабы 2 — неверный пароль и logout. С
лабы 4 к ним SHALL добавиться слишком большой файл, повреждённое
изображение, подмена MIME, чужое `attachment_id` и вложение другого
чата. Каждый такой тест SHALL проверять, что ошибка клиента дала
статус 4xx в формате контракта, а не 500.
#### Scenario: Неверный JSON
- **WHEN** тест отправляет тело `{bad` в эндпоинт, ожидающий JSON
- **THEN** проверяется ответ 400 с `code` `invalid_request`
#### Scenario: Чужой чат
- **WHEN** пользователь, не состоящий в чате, читает чат, читает
историю и пишет в чат
- **THEN** проверяется, что все три запроса получают 404 `not_found`
#### Scenario: Пустое сообщение
- **WHEN** участник отправляет сообщение с `text` пустым и из пробелов
- **THEN** проверяется ответ 400 `invalid_request`, и сообщение не
появляется в истории
#### Scenario: Дубликат username
- **WHEN** регистрируется `username`, который уже занят
- **THEN** проверяется ответ 409 `conflict`
#### Scenario: Обход нескольких страниц
- **WHEN** история содержит больше сообщений, чем помещается на одну
страницу, и тест обходит её по `next_cursor`, в том числе меняя
`limit` между страницами
- **THEN** проверяется, что каждое сообщение встречается ровно один раз
в порядке `(created_at, id)`, а последняя страница имеет
`next_cursor` null
#### Scenario: Неверный пароль в рубрике
- **WHEN** зарегистрированный пользователь входит с неверным паролем
- **THEN** проверяется ответ 401 с `WWW-Authenticate` схемы `Basic`, и
выданного токена в ответе нет
#### Scenario: Logout в рубрике
- **WHEN** пользователь выходит, а затем повторяет запрос прежним
токеном
- **THEN** проверяется ответ 204 на выход и 401 с `WWW-Authenticate`
схемы `Bearer` на повтор
#### Scenario: Слишком большой файл в рубрике
- **WHEN** участник загружает файл больше 10 MiB с `Content-Length` и
частями без него
- **THEN** проверяется ответ 413 `payload_too_large` в обоих случаях
#### Scenario: Повреждённое изображение в рубрике
- **WHEN** участник загружает обрезанные PNG и JPEG и PNG с изменённым
байтом данных
- **THEN** проверяется ответ 415 `unsupported_media_type` на каждый
#### Scenario: Подмена MIME в рубрике
- **WHEN** участник загружает JPEG с `Content-Type: image/png` и текст с
`Content-Type: image/jpeg`
- **THEN** проверяется ответ 415 `unsupported_media_type` на оба
#### Scenario: Чужое attachment_id в рубрике
- **WHEN** участник отправляет сообщение с вложением чата, где он не
состоит, и с неизвестным id вложения, а посторонний читает метаданные
и байты вложения
- **THEN** проверяется ответ 404 `not_found` на каждый запрос
#### Scenario: Вложение другого чата в рубрике
- **WHEN** участник двух чатов отправляет в один из них сообщение с
вложением другого
- **THEN** проверяется ответ 404 `not_found`, и сообщение не появляется
в истории
### Requirement: Покрытие сценариев основных спеков
Для каждого сценария основных спеков `api-conventions`,
`identification`, `sessions`, `users`, `chats`, `messages`,
`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency` и с
лабы 4 `attachments`, который воспроизводится по HTTP против
работающего сервера, в том числе на стенде отказов, SHALL быть тест. Из
имени или описания теста SHALL быть понятно, какой capability и
сценарий он проверяет. Сценарий, который проверяет тест отказа, SHALL
считаться покрытым, хотя `make student_test` этот тест не выполняет;
итог сверки SHALL называть, сколько сценариев покрыто проверками
отказов. Сценарии, которые по HTTP не воспроизвести, SHALL быть
перечислены с причиной и способом проверки.
#### Scenario: Сверка покрытия
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
- **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной
#### Scenario: Сценарий отказа в сверке
- **WHEN** выполняется `make student_test`
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
требует для них исключений и печатает их число
### Requirement: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
объектов недоступно»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша»;
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
«Ключ после срока»;
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
не оставляет», «S3 остановлен», «S3 завис».
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить
миграции и bootstrap S3;
- запустить два API: с настройками по умолчанию и «тесный» — с
коротким сроком сессии и ключа идемпотентности и пулом из одного
соединения;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Hook стенда отказов SHALL уметь сообщить число вложений в PostgreSQL
стенда по статусам и число объектов вложений в его bucket. Других
сведений о хранилищах проверки вложений не получают.
Порты PostgreSQL, Valkey и S3 этого стенда MUST NOT публиковаться на
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
хранилище объектов и контейнеры MUST NOT затрагиваться. Код выхода
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
начале второго удаляет стенд первого.
#### Scenario: Успешный прогон
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
volumes стенда отказов после команды нет, а у контейнеров рабочего
стенда прежнее время старта, и рабочий API отвечает
#### Scenario: Упавшая проверка
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
- **THEN** код выхода ненулевой, журналы API стенда отказов выведены,
стенд отказов удалён
#### Scenario: Прерывание
- **WHEN** `make failure_checks` прерван Ctrl+C
- **THEN** стенд отказов остановлен и удалён вместе с volumes
#### Scenario: Хвост прошлого прогона
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
убитого без уборки
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
### Requirement: Результат прогона сохраняется
Вывод прогона против контейнера (`make test_isolated`), вывод `make
student_test` против стенда с балансировщиком и вывод `make
failure_checks` SHALL сохраняться в `evidence/` с командой, датой,
commit, адресом стенда и итогом. `REPORT.md` SHALL ссылаться на них в
строках уровня «4»: собственные тесты, 100 сообщений от 10 клиентов,
гонка одного ключа через реплики, автоматические проверки истечения
сессии и недоступности БД и Valkey, а с лабы 4 — негативные тесты
вложений и проверки отказов S3.
#### Scenario: Доказательство в отчёте
- **WHEN** проверяющий открывает строку уровня «4» в `REPORT.md`
- **THEN** в ней есть команда, наблюдаемый результат и путь к файлу
вывода в `evidence/`
### Requirement: Доказательства исключений сверки в репозитории
Если способ проверки сценария из списка исключений сверки покрытия
ссылается на файл в `evidence/`, этот файл SHALL лежать в репозитории
текущей лабы. В нём SHALL быть результат, снятый на стенде этой лабы,
команда, дата и commit. Если способ проверки — команда, которая сама
снимает доказательство на стенде, исключение SHALL её называть.
Сверка покрытия SHALL падать, если файла по ссылке исключения нет, и
называть сценарий и путь.
Такое доказательство MUST NOT содержать токенов, паролей и их хэшей
целиком, ключей доступа и секретов S3 — только факты, счётчики и
префиксы.
#### Scenario: Ссылка на отсутствующий файл
- **WHEN** исключение ссылается на файл `evidence/…`, которого нет в
репозитории
- **THEN** `make student_test` завершается с ненулевым кодом, а
сообщение называет сценарий и путь
#### Scenario: Кэш и хранение секретов на стенде лабы
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
`chat-cache` «Чтение из кэша», «Срок записи», «Временная база»,
`sessions` «Токена нет в хранилище» и `users` «Хэш в БД»
- **THEN** в них вывод названной в исключении команды на стенде с
балансировщиком и двумя репликами, дата и commit, а токенов, паролей
и полных хэшей нет
#### Scenario: Вложения на стенде лабы
- **WHEN** проверяющий открывает файлы, на которые ссылаются исключения
`attachments` «Принявшая реплика остановлена», «Байты не в БД и не на
диске API» и «Рестарт стенда»
- **THEN** в них вывод названной в исключении команды на стенде с
балансировщиком, двумя репликами и S3, дата и commit, SHA-256
загруженного и скачанного файла, а токенов и секретов S3 нет
+345
View File
@@ -0,0 +1,345 @@
# 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 — текст из одних пробелов с вложением даёт 400. Это временная
трактовка до ответа преподавателя (design, решение 8). Если ответ
другой, меняются условие валидатора `CreateMessage`, сценарий
`messages` «Пробелы с вложением» и его тест, а ответ записывается в
AGENTS.md, «Согласования с преподавателем»;
- п. 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`, временная трактовка текста из пробелов с вложением;
- `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 .`.
## 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» с командой, наблюдением и файлом;
- ограничения;
- открытый вопрос преподавателю: текст из одних пробелов с вложением
пока даёт 400 (design, решение 8).
Строку этапа 2 в `PLAN.md` — по факту. Проверка: у каждой новой строки
таблицы доказательств есть команда, наблюдение и файл; `make lint`,
`make check`, `openspec validate attachments --strict`. Коммит — после
подтверждения.