Propose PNG header consistency as an OpenSpec change

This commit is contained in:
Artyom
2026-11-06 21:29:25 +03:00
parent 7342d5d97a
commit bcbd4ebc02
5 changed files with 102 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
@@ -0,0 +1,26 @@
## Context
См. `proposal.md`. Изменение остаётся в адаптере `PillowImageInspector` порта `ImageInspector`, зона attachments; сборка — `attachments/entrypoints/ioc.py`. Сейчас Pillow и проверка строк независимо выбирают заголовки. Context7 `/python-pillow/pillow/13.0.0` подтверждает ленивый `Image.open` и отсутствие декодирования в `verify`.
## Goals / Non-Goals
**Goals:** один однозначный IHDR для размеров, лимита и структуры строк; ранний `415` при повторном заголовке без побочных записей.
**Non-Goals:** полный пиксельный буфер, изменение поддержки JPEG, APNG-кадров, границ зон, схемы, SQL, конкурентности или контейнеров.
## Decisions
1. До Pillow пройти границы PNG-чанков без копирования тела: первым должен быть IHDR длины 13, последующих IHDR до IEND быть не должно. Простая сверка размеров недостаточна: одинаковые размеры могут скрывать разные глубину цвета, цветовой тип или interlace. Только запрет повторов устраняет неоднозначность.
2. Разобрать единственный заголовок один раз и передать его и в лимит пикселей/метаданные, и в проверку строк. Pillow сохраняет проверку типа и CRC. Полный `load()` для PNG не нужен: ограниченная распаковка по 64 KiB остаётся прежней.
3. Существующий порядок: аутентификация → лимит объявленного/потокового тела 10 MiB → проверка заголовка и лимит 40 MP → CRC и пиксели → intent/COMMIT → PUT → ready/COMMIT. Ошибка заголовка возникает до intent; PostgreSQL и S3 не затрагиваются. Слоты upload и инспектора, thread-offload, таймауты и компенсация остаются прежними.
4. Регрессия содержит точный файл ревью (94 байта), одинаковый повтор, смену параметров/размеров, повтор после IDAT и неверную позицию первого IHDR. Отдельная ASGI-проверка подтверждает `415` и отсутствие вызовов записи; API/LB матрицы получают тот же файл для финального прогона.
## Risks / Trade-offs
- Дополнительный проход по чанкам — O(число чанков) времени и O(1) памяти; тело уже ограничено 10 MiB. Границы длины проверяются до извлечения данных. Тесты широких строк, Adam7, цветовых форматов и лимита 40 MP сохраняются.
- Невалидные PNG, терпимо принимаемые Pillow, получают `415`. Это соответствует требованию о повреждённых файлах. Корректные изображения подтверждаются положительной матрицей.
- RSS/cgroup и конкурентная HTTP-нагрузка этим этапом не проверяются. Новая проверка входит в upload; финальный агент исполняет затронутые проверки из `evidence/png-header-fix/NOTES.md`, сохраняя пригодные прежние серии.
## Migration Plan
Миграция данных не нужна. Применить код после offline-проверок, синхронизировать спецификацию и архивировать цикл. Следующий этап пересобирает API и выполняет обозначенные динамические проверки. Возврат старого инспектора возвращает major.
@@ -0,0 +1,27 @@
## Why
Ревью snapshot `7342d5d97a5e50659a6c44c56d5a87e62aa87c1f` выявило major: PNG с двумя IHDR проходит проверку потока по первому заголовку, тогда как Pillow использует второй. Повреждённый файл получает `201` вместо обязательного `415` — нарушен критерий проверки содержимого уровня «3» и негативных файлов уровня «4» в `README.md` и `contracts/README.md`.
## What Changes
- Отклонять повторный или неверно расположенный IHDR до распаковки; лимит пикселей и проверка строк используют один разобранный заголовок.
- Добавить регрессии инспектора и ASGI upload без записи в хранилища, расширить собственные API/LB негативные матрицы.
- Сохранить offline-доказательства и список затронутых динамических проверок для финального агента.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `lab4-attachments`: уточнить отказ `415` при неоднозначном PNG-заголовке и отсутствие записи вложения.
## Impact
Зона attachments, собственные тесты, OpenSpec и `evidence/png-header-fix/`. Строка будущей таблицы `REPORT.md`: «Тип по содержимому, битые и обрезанные файлы → make upload-faults». Финальный отчёт принадлежит отдельному этапу; прежние evidence сохраняются с исходными SHA.
## Non-goals
Не входят minor Unicode-суррогатов, изменение хранилищ, SQLAlchemy/Alembic и контейнеров. Сохраняется Out of scope из `openspec/config.yaml`: worker, варианты изображений, брокер, presigned и возможности лаб 5–7. Docker, нагрузка, публикация и Telegram на этом этапе запрещены.
@@ -0,0 +1,36 @@
## MODIFIED Requirements
### Requirement: Тип определяется по содержимому
Сервис SHALL принимать только `Content-Type` `image/png` и `image/jpeg` (параметры заголовка и регистр не важны) и SHALL проверять, что сигнатура и структура файла соответствуют заявленному типу, а файл читается без ошибок. Иной или отсутствующий `Content-Type`, несовпадение заявленного типа и содержимого, пустое тело, обрезанный или повреждённый файл, GIF, WebP и текст SHALL давать `415` с кодом `unsupported_media_type`.
#### Scenario: Подмена MIME
- **WHEN** JPEG, GIF или текст отправлены с `Content-Type: image/png`
- **THEN** ответ `415` с кодом `unsupported_media_type`
#### Scenario: Обрезанное изображение
- **WHEN** отправлена первая половина корректного PNG или JPEG с верным `Content-Type`
- **THEN** ответ `415`
#### Scenario: Неподдерживаемый Content-Type
- **WHEN** корректный PNG отправлен с `Content-Type: application/octet-stream` или без `Content-Type`
- **THEN** ответ `415`
#### Scenario: Повреждённый поток пикселей при корректных CRC
- **WHEN** участник отправляет PNG с корректными CRC и IEND, но ошибочным zlib-потоком IDAT, его контрольной суммой, числом байтов строк или кодом фильтра
- **THEN** `POST /api/v1/chats/{chat_id}/attachments` отвечает `415` с кодом `unsupported_media_type`, `X-Request-Id` и `X-Instance-Id`; строка вложения и объект не создаются
#### Scenario: Корректные варианты PNG
- **WHEN** участник загружает корректный PNG в пределах лимитов, в том числе Adam7, с разрешёнными глубиной цвета и фильтрами, а IDAT разделён на несколько чанков
- **THEN** ответ `201 ready`, скачивание другим участником возвращает исходные байты
#### Scenario: Неоднозначный заголовок PNG
- **WHEN** участник отправляет PNG с повторным IHDR до IEND, даже при одинаковых размерах и корректных CRC, или с IHDR не первым чанком
- **THEN** `POST /api/v1/chats/{chat_id}/attachments` отвечает `415` с кодом `unsupported_media_type`, `X-Request-Id` и `X-Instance-Id`; строка вложения и объект не создаются
@@ -0,0 +1,11 @@
## 1. Attachments: уровни «3» и «4»
- [ ] 1.1 Добавить точный PNG из ревью и offline-регрессии инспектора/ASGI; подтвердить отказ тестов на исходном коде.
- [ ] 1.2 Исключить неоднозначный IHDR и передавать один заголовок в лимит пикселей и проверку строк; выполнить целевые unit-тесты.
- [ ] 1.3 Добавить файл в собственные API/LB негативные матрицы и проверить их collection без исполнения Docker-fixtures.
## 2. Offline-проверки и evidence
- [ ] 2.1 Выполнить unit-suite, статические границы зон, make check, make validate, make lint и строгую OpenSpec validation; сохранить реальные выводы.
- [ ] 2.2 Записать область применимости прежних evidence и обязательные динамические проверки финального этапа без их запуска; сохранить известный minor в заметках.
- [ ] 2.3 Синхронизировать спецификацию, архивировать цикл и зафиксировать английские коммиты после make lint.