diff --git a/.claude/rules/api-contract.md b/.claude/rules/api-contract.md index 337736a6..705e7293 100644 --- a/.claude/rules/api-contract.md +++ b/.claude/rules/api-contract.md @@ -289,7 +289,11 @@ ACTION_SCRIPT=scripts/restart.sh` (`tests/README.md`), hook — U+007F–U+009F) и строка из одних пробелов. Символы форматирования и направления текста (Cf, U+202E, U+2066), U+2028/U+2029 принимаются и возвращаются без изменений (решение пользователя 2026-10-20). Имя - только отображается: ни в ключ, ни в путь, ни в журнал. + только отображается: ни в ключ, ни в путь, ни в журнал. Процент-коды + `filename` — строгий UTF-8: Starlette меняет неверные байты на U+FFFD + (`a%FFb.png` прошёл бы с 201), поэтому ручка сама разбирает + `scope["query_string"]` (`_check_filename_encoding`): неверный UTF-8 и + байт вне ASCII — `InvalidFilename` (400) до проверки членства. - `attachment_id` в пути и элементы `attachment_ids` в теле — `UuidIn` (раздел «Валидация → 400»). `attachment_ids`: 0–10, без повторов (и в другом регистре), иначе 400; каждое — готовое вложение этого чата, diff --git a/.claude/rules/api-layer.md b/.claude/rules/api-layer.md index 54e0a764..7d3622d9 100644 --- a/.claude/rules/api-layer.md +++ b/.claude/rules/api-layer.md @@ -74,7 +74,10 @@ FastAPI, один процесс на реплику; реплик ≥2 за HAP асинхронным итератором поверх `request.stream()`, обёртка переводит `ClientDisconnect` в доменное `UploadInterrupted` (400): в итоговой записи 400, а не 500 с traceback. `Content-Type` — тип до `;`, без - пробелов, в нижнем регистре; `Content-Length` — `int` или `None`; + пробелов, в нижнем регистре; `Content-Length` — `int` или `None`. + До сервиса ручка проверяет кодировку `filename` по сырой строке + запроса (`_check_filename_encoding` → `InvalidFilename`, 400): + Starlette заменил бы неверный UTF-8 на U+FFFD (`api-contract.md`); - скачивание — `StreamingResponse` над генератором блоков объекта S3: `media_type` вложения (у `image/*` Starlette `charset` не добавляет), `Content-Length`, `X-Content-Type-Options: nosniff`; генератор сам diff --git a/.claude/rules/docker.md b/.claude/rules/docker.md index 4ff4d8e9..2b0ef2ee 100644 --- a/.claude/rules/docker.md +++ b/.claude/rules/docker.md @@ -59,6 +59,12 @@ paths: init есть — по другой причине (`student-tests.md`). - `ENV APP__RUN_MODE=docker PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1`, `EXPOSE 8080`. +- С лабы 4 ещё `MALLOC_MMAP_THRESHOLD_=131072`: блоки glibc от 128 KiB + всегда в mmap, и буфер тела загрузки растёт через `mremap`, без копии. + Без него порог динамический: после первой загрузки glibc поднимает его + до ~10 MiB, следующие буферы растут в куче, и `realloc` на миг держит + два тела (замер — design change `attachments`, «Уточнения apply», + п. 10). Не убирать без нового замера. - `HEALTHCHECK` на `/health/ready` через `python -c "import urllib.request; ..."` (curl в slim нет) с явными `--interval`, `--timeout`, `--start-period` и `--start-interval=1s`: без него первая diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 4bc5f429..6b3f437e 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -99,8 +99,9 @@ paths: время, `assert_content` (байты, тип, длина, `nosniff`, без `Location` и `x-amz-*`); - проверки отказов (`test_failures.py`): «Запись в S3 не удалась», - «Отклонённая загрузка ничего не оставляет», «S3 остановлен», «S3 - завис». Hook — `count-attachments` (`pending=N ready=M` через psql) и + «Отклонённая загрузка ничего не оставляет», «S3 остановлен» (с + историей `attachment_ids` без S3), «S3 завис»; вне сверки — «Окружение + не меняет лимит» спека `service-configuration`. Hook — `count-attachments` (`pending=N ready=M` через psql) и `count-objects` (каталоги `` под `/buckets//<база>/ attachments` через `weed shell` в контейнере `s3`; bucket и база — `FAULT_S3_BUCKET`, `FAULT_DATABASE` от `run_failures.py` из @@ -174,7 +175,10 @@ paths: healthcheck PostgreSQL проверяет служебную базу `postgres` (иначе каждая проверка — сессия в базе приложения и шум счётчика `db-sessions`); - - два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`) и + - два API на свободных портах `127.0.0.1`: обычный (`BASE_URL`; с + лабы 4 в окружении `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` — + `LIMITS_ENV`, тест получает их в `FAULT_LIMITS_ENV` и грузит + `sample.png`: лимиты — константы, спек `service-configuration`) и «тесный» (`FAULT_TIGHT_BASE_URL`: сроки сессии и ключа идемпотентности 2 с, пул 1, короткие таймауты); - `pytest -m fault`, затем журнал PostgreSQL стенда: сводка `postgres diff --git a/AGENTS.md b/AGENTS.md index d61a02b9..e30fe08e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -338,7 +338,7 @@ src/ config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации - routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra), метаданные, байты StreamingResponse + routers/v1/.py # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py); attachment.py — один роутер с двумя префиксами: загрузка (тело через request.stream(), схема — openapi_extra, строгий UTF-8 filename по scope["query_string"]), метаданные, байты StreamingResponse schemas/.py # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12; attachment.py — DisplayFilename (отказ на / \ Cc и пробелы) и Attachment; message.py — CreateMessage с attachment_ids и валидатором пустого текста dependencies.py # db_session_scope (сессия на шаг) и get_db_session поверх него, фабрики сервисов (с кэшем; вложения — без сессии запроса), разбор Basic, текущая сессия по Bearer, CurrentUserBrief (вход с короткой сессией), пагинация errors.py # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id @@ -351,7 +351,7 @@ src/ repos/attachment_object.py # оригинал в S3: ключ <база>/attachments//original, put, open repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией - services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком → структура и SHA-256 в потоке → pending → PUT → ready), метаданные, отдача потоком + services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком в BytesIO, bytes без копии → структура и SHA-256 в потоке → pending → PUT → ready), метаданные, отдача потоком exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan @@ -410,7 +410,7 @@ infra/ # конфигурации сервисов сте scripts/restart.sh # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey, s3 (~25 с); start api повторяет migrate и s3-bootstrap (no-op) scripts/stop-one.sh # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG scripts/rolling-update.sh # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/ -Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck +Dockerfile # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck, MALLOC_MMAP_THRESHOLD_ (буфер загрузки растёт без копии) docker-compose.yml # проект mtusi-lab4: postgres, valkey, s3 (SeaweedFS, служебное на loopback, API S3 на 127.0.0.1:S3_OUT_PORT), migrate, s3-bootstrap, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volumes postgres_data и s3_data, лимиты у всех, окружение и секреты по сервисам (x-db-env, x-cache-env, x-s3-env) .dockerignore config_example.toml, .env.example diff --git a/Dockerfile b/Dockerfile index d37ddf98..a5d1c99b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -29,9 +29,14 @@ RUN groupadd --system --gid 10001 app \ && useradd --system --uid 10001 --gid app --no-create-home \ --home-dir /nonexistent --shell /usr/sbin/nologin app +# MALLOC_MMAP_THRESHOLD_: блоки от 128 KiB всегда в mmap, и буфер тела +# загрузки растёт через mremap без копии. Без него glibc после первой +# загрузки поднимает порог, буфер растёт в куче, и realloc на миг держит +# два тела (design change `attachments`, решение 6) ENV PATH=/app/.venv/bin:$PATH \ PYTHONUNBUFFERED=1 \ PYTHONDONTWRITEBYTECODE=1 \ + MALLOC_MMAP_THRESHOLD_=131072 \ APP__RUN_MODE=docker WORKDIR /app diff --git a/PLAN.md b/PLAN.md index 1bea41ee..133cf601 100644 --- a/PLAN.md +++ b/PLAN.md @@ -350,6 +350,10 @@ SHA-256. вставки строки после PUT (триггер, как `fail-messages`); kill реплики посреди загрузки; обрыв клиента посреди тела. Итог каждого: нет 500, `pending` убран уборщиком после grace period, объектов без строки нет. +Ещё — невидимость `pending` через API (замечание verify `attachments`, +S6; спек `attachments`, «Порядок записи»): действие hook с id последней +строки `pending` (после «Запись в S3 не удалась»), по нему метаданные, +байты и сообщение со ссылкой — 404 до уборки. **Спеки (дельты).** `attachments` (сбои загрузки), новая или в `object-storage` — уборка. @@ -694,6 +698,33 @@ apply»): LB (design, «Уточнения apply», п. 9); запись `KNOWN_ISSUES.md` удалена. +Замечания `/opsx:verify` 2026-10-21 (все приняты, tasks группа 10; +design, «Уточнения apply», пп. 10–15): + +19. **Память загрузки — одно тело, а не два.** Тело копится в + `io.BytesIO`, `getvalue()` отдаёт `bytes` без копии (`bytearray` + botocore копирует). В образе — `MALLOC_MMAP_THRESHOLD_=131072`: с + динамическим порогом glibc вторая загрузка росла в куче, и `realloc` + на миг держал два тела. Замер в образе: RSS 1,99 → 1,19–1,20 тела на + каждой из трёх загрузок подряд. Буфер под `Content-Length` заранее + не выделяется: заявивший 10 MiB клиент держал бы их без передачи. +20. **«Бомба» распаковывается до ожидаемого объёма + 1 байт**, а не до + 1 MiB: предел блока zlib — остаток ожидаемого плюс байт. Корпус + 11 993 файлов — вердикты те же. +21. **«Старый образ на новой схеме»** переформулирован: проверки, которые + прежний образ проходил на прежней схеме, проходят и на новой; + доказательство — замер `rollout` (переснять с чистого дерева после + commit правок). +22. **`filename` не в UTF-8 — 400** (`a%FFb.png` давал 201 с U+FFFD): + ручка строго разбирает строку запроса, новый сценарий «Имя не в + UTF-8». +23. **«Окружение не меняет лимит»** проверяет тест `fault`: обычный API + стенда отказов — с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`. +24. **Мёртвые константы** `MESSAGE_TEXT_MIN_LENGTH` и + `ATTACHMENT_READ_CHUNK_BYTES` удалены: блок чтения задаёт uvicorn. +25. **Невидимость `pending` через API** (S6) — не здесь: задача + `upload-consistency` (раздел «Последовательность работ», п. 3). + #### Вопросы 1. Что считать «повреждённым изображением» (решение 2, спек diff --git a/openspec/changes/attachments/design.md b/openspec/changes/attachments/design.md index c579ef8f..a3f0ee27 100644 --- a/openspec/changes/attachments/design.md +++ b/openspec/changes/attachments/design.md @@ -381,13 +381,24 @@ VALUE` нельзя использовать в той же транзакции - Сервис: - `media_type` не PNG и не JPEG — 415 до тела; - `Content-Length` больше лимита — 413 до тела; - - чтение в `bytearray` со счётчиком: больше лимита — 413 сразу, без + - чтение в `io.BytesIO` со счётчиком: больше лимита — 413 сразу, без дочитывания; - - затем один `bytes(...)`. -- Пик памяти загрузки — около двух тел (буфер и копия), пока не - отработал PUT. botocore считает CRC32 потоком, без копии. Сколько - таких загрузок помещается в 512 МБ и чем их ограничить — - `upload-memory`. + - затем `getvalue()` — `bytes` над тем же буфером, без копии + (CPython отдаёт внутренний объект, если на буфер нет ссылок). + Именно `bytes`: botocore оборачивает тело `PutObject` в `BytesIO` + без копии только для `bytes`, а `bytearray` копирует + (`httpchecksum`), `inspect_image` и `hashlib` принимают оба. +- Пик памяти загрузки — одно тело и блок чтения, пока не отработал PUT; + botocore читает тело для подписи и CRC32 блоками по 1 MiB. Рост + буфера без копии в образе даёт `MALLOC_MMAP_THRESHOLD_=131072` + (`Dockerfile`): с динамическим порогом glibc после первой загрузки + растит буфер в куче, и `realloc` на миг держит два тела. Замер — + «Уточнения apply», п. 10. Сколько таких загрузок помещается в 512 МБ и + чем их ограничить — `upload-memory`. + + *Альтернатива:* сразу выделить буфер под `Content-Length`. Отвергнута: + клиент, заявивший 10 MiB и не шлющий тело, держал бы 10 MiB с первого + байта, а не по мере передачи. - `Content-Length: 0` и пустое тело — 415 (не изображение). - Ответы 404, 413 и 415 до чтения тела доходят до httpx, до curl и до любого клиента через LB (Context). `urllib` напрямую к одной реплике @@ -702,10 +713,10 @@ VALUE` нельзя использовать в той же транзакции - [CPU проверки: до ~0,3 с на «узкий» PNG и ~0,1 с на JPEG из вставок] → в потоке, event loop не стоит. Лимит параллельных загрузок — `upload-memory`. -- [Память загрузки ~2 × тело без лимита конкурентности: около 30 - одновременных загрузок по 10 MiB доводят реплику 512 МБ до OOM] → - граница описана, лимит и замер — `upload-memory`. До него нагрузочные - прогоны загрузок не запускаются. +- [Память загрузки ~1,2 тела (тело и блоки чтения botocore) без лимита + конкурентности: около 30 одновременных загрузок по 10 MiB (~12,5 МБ + каждая сверх ~120 МБ базы реплики) доводят реплику 512 МБ до OOM] → граница описана, лимит и замер — + `upload-memory`. До него нагрузочные прогоны загрузок не запускаются. - [PUT 10 MiB со сроком 5 с: под очередью S3 последняя из 20 одновременных записей подтверждена через 7,2 с] → 503 и строка `pending`, клиент повторяет загрузку. Срок PUT и лимит конкурентности @@ -822,6 +833,65 @@ VALUE` нельзя использовать в той же транзакции трижды — код 0; `bench_quick`, `bench_failover_quick`, `bench_rollout_quick` — код 0. +Замечания `/opsx:verify` 2026-10-21 (задачи группы 10): + +10. **Память загрузки — одно тело** (W1, решение 6). Проба + (scratchpad `mem_probe.py`) в образе API (Linux, CPython образа), + код сервиса — смонтированный `src` до и после правки: тело PNG + 10 449 063 байт блоками по 64 KiB через `_read_body`, затем `_inspect` + (структура и SHA-256) и то, что botocore делает с `bytes` (`BytesIO` + и SHA-256 блоками по 1 MiB); три загрузки подряд в одном процессе, + пик RSS — `VmHWM` со сбросом через `/proc/self/clear_refs` перед + каждой, `tracemalloc` — по стадиям. В долях тела: + + | Код | Порог mmap glibc | RSS: загрузка 1 / 2 / 3 | `tracemalloc`: чтение / проверка / тело PUT | + |---|---|---|---| + | до (`bytearray` + `bytes(...)`) | динамический | 2,11 / 1,80 / — ¹ | 2,10 / 1,02 / 1,20 | + | после (`BytesIO` + `getvalue()`) | динамический | 1,25 / 2,05 / 1,07 | 1,11 / 1,02 / 1,20 | + | до | 131072 | 1,99 / 1,99 / 1,99 | — | + | после | 131072 | 1,20 / 1,19 / 1,19 | — | + + ¹ освобождённая куча второй загрузки осталась резидентной, рост 0. + + Без копии `getvalue()` чтение даёт одно тело, но со вторым запуском + glibc поднимает динамический порог mmap до размера освобождённого + буфера, буфер растёт в куче, и `realloc` на миг держит два тела (2,05). + Фиксированный порог 128 KiB (`MALLOC_MMAP_THRESHOLD_` в + `Dockerfile`) держит буфер в mmap, рост — `mremap` без копии: 1,00 + тела на чтении и 1,19–1,20 с блоками botocore на каждой загрузке. + `tracemalloc` на чтении — 1,11: он считает запас ёмкости `BytesIO` + (до 1/8), страницы запаса не заполняются, RSS их не видит. +11. **«Бомба» — до ожидаемого объёма + 1 байт** (W2, решение 2). Блок + распаковки ограничивался только 1 MiB, и PNG 100 × 100 с IDAT на + 200 MiB распаковывался на 1 048 576 байт при ожидаемых 30 100. + `max_length = min(1 MiB, ожидаемое − распаковано + 1)`, выход из + цикла — по нему. Проба `probe_inflate.py`: 30 101 байт, затем + `DamagedImage`. Корпус 11 993 PNG и JPEG системы (выборка 12 000, + seed 20261021): вердикт нового модуля совпал с HEAD у всех, ложных + отказов против Pillow 0, только по пикселям — 4. +12. **«Старый образ на новой схеме»** (W3, дельта `db-migrations`): + `make test` и `make student_test` образа `e1161f7` красные с лабой 4 + на любой схеме — у него нет вложений. Сценарий переформулирован: + проверки, которые прежний образ проходил на прежней схеме, проходят + и на новой (запись 201, история 200, без 5xx), доказательство — + `evidence/rollout/attachments/summary.md`. +13. **`filename` не в UTF-8 — 400** (S3, решение 10). Starlette + декодирует процент-коды с заменой неверных байтов на U+FFFD, и + `a%FFb.png` давал 201. Ручка до вызова сервиса разбирает + `scope["query_string"]` сама (те же пары, что `parse_qsl`) и + отвечает `InvalidFilename` (400) на неверный UTF-8 и байт вне ASCII; + для принятых значений результат совпадает со Starlette. Порядок + проверок прежний: 400 параметров до 404 членства. Новый сценарий + спека — «Имя не в UTF-8», тест `test_filename_not_utf8`. +14. **«Окружение не меняет лимит»** (S4, дельта + `service-configuration`): обычный API стенда отказов запускается с + `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1`, тест `fault` сверяет, + что стенд запущен с ними (`FAULT_LIMITS_ENV`), и грузит + `sample.png` — 201. +15. **Невидимость `pending` через API** (S6) по HTTP не вызвать без + строки `pending` на стенде отказов: проверка — в `upload-consistency` + (действие hook с id последней `pending`, `PLAN.md`). + ## Open Questions - ~~Текст из одних пробелов вместе с вложением~~ — закрыт 2026-10-20 diff --git a/openspec/changes/attachments/specs/attachments/spec.md b/openspec/changes/attachments/specs/attachments/spec.md index 6268bf3a..b45f04dd 100644 --- a/openspec/changes/attachments/specs/attachments/spec.md +++ b/openspec/changes/attachments/specs/attachments/spec.md @@ -200,11 +200,25 @@ PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ Cf, например U+202E и U+2066); - разделители строк и абзацев U+2028 и U+2029. +Имя в строке запроса SHALL быть корректным UTF-8 после +процент-декодирования. Неверная последовательность байтов (например, +`%FF`, обрезанная или закодированный суррогат) и байт вне ASCII в +строке запроса — 400 `invalid_request`. Замена таких байтов символом +U+FFFD MUST NOT превращать отказ в принятое имя. + Принятое имя SHALL храниться и возвращаться без изменений, без обрезки и нормализации. Имя только отображается: оно MUST NOT участвовать в ключе объекта и в пути на диске. Как безопасно показать имя, решает клиент. +#### Scenario: Имя не в UTF-8 + +- **WHEN** участник загружает настоящий PNG с `filename=a%FFb.png`, + `filename=a%C3.png` и `filename=a%ED%A0%80b.png`, а затем с + `filename=%C3%A9t%C3%A9.png` +- **THEN** первые три ответа 400 `invalid_request`, последний — 201 с + `filename` `été.png` + #### Scenario: Опасное имя - **WHEN** участник загружает настоящий PNG с `filename` diff --git a/openspec/changes/attachments/specs/db-migrations/spec.md b/openspec/changes/attachments/specs/db-migrations/spec.md index 348af149..41f73f08 100644 --- a/openspec/changes/attachments/specs/db-migrations/spec.md +++ b/openspec/changes/attachments/specs/db-migrations/spec.md @@ -40,8 +40,13 @@ - **WHEN** стенд работает на образе прежнего commit, и миграции нового образа применены, а реплики не заменены -- **THEN** `make test` и `make student_test` через LB проходят на - прежних репликах +- **THEN** проверки, которые прежний образ проходил на прежней схеме, + проходят и на новой: запись сообщений через прежние реплики — 201, + история — 200, ответов 5xx нет (замер замены реплик — + `evidence/rollout/attachments/summary.md`) +- **AND** проверки, которых прежний образ не проходил и на прежней схеме + (новые требования контракта, например вложения лабы 4 для образа лабы + 4 до `attachments`), совместимостью схемы не считаются #### Scenario: Запись прежней версии diff --git a/openspec/changes/attachments/tasks.md b/openspec/changes/attachments/tasks.md index ae79d13b..0c16f802 100644 --- a/openspec/changes/attachments/tasks.md +++ b/openspec/changes/attachments/tasks.md @@ -351,3 +351,62 @@ таблицы доказательств есть команда, наблюдение и файл; `make lint`, `make check`, `openspec validate attachments --strict`. Коммит — после подтверждения. + +## 10. Замечания проверки + +Находки `/opsx:verify` 2026-10-21, все решено исправить. Требования +меняются и в дельте change, и в основном спеке (они синхронизированы). +Порядок: код и документы 10.1–10.3, 10.5–10.8 → проверки 10.9 → commit +основной сессией → 10.4 на чистом дереве. Невидимость `pending` через +API (S6) — задача change `upload-consistency` (`PLAN.md`). + +- [x] 10.1 W1. Тело загрузки без второй копии: `_read_body` копит блоки + в `io.BytesIO` и отдаёт `getvalue()` — `bytes` над тем же буфером, без + копии; `inspect_image`, `hashlib` и botocore (`PutObject` оборачивает + `bytes` в `BytesIO` без копии, `bytearray` копирует) получают `bytes`. + В образе `MALLOC_MMAP_THRESHOLD_=131072`: с динамическим порогом glibc + вторая загрузка росла в куче с копией в `realloc`. Design (решение 6, + Risks), правило `docker.md`; строка `REPORT.md` («~2 тела») — в 10.4, + после commit. Проверка: пик памяти чтения тела 10 MiB блоками по + 64 KiB с проверкой и SHA-256 до и после — `tracemalloc` и `VmHWM` в + образе API (Linux, CPython образа), три загрузки подряд, итог — в + design, «Уточнения apply», п. 10. +- [x] 10.2 W2. `_IdatStream._inflate`: `max_length = min(предел блока, + ожидаемое − распаковано + 1)`, выход из цикла — по этому `max_length`. + Проверка: проба `probe_inflate.py` (scratchpad) — «бомба» распакована + не больше ожидаемого + 1; корпус задачи 1.2 без новых отказов; + `test_attachments.py` зелёный. +- [x] 10.3 W3. Сценарий `db-migrations` «Старый образ на новой схеме» + (дельта и основной спек): проверки, которые прежний образ проходил на + прежней схеме, проходят и на новой; запись и история через прежние + реплики — 201 и 200; доказательство — + `evidence/rollout/attachments/summary.md`. Проверка: `openspec + validate` change и спеков. +- [ ] 10.4 S1. Пересъёмка `evidence/rollout/attachments/` с чистого + дерева после commit правок: старую метку удалить, проверка хоста, + рабочий стенд — `make stop`, `make bench_rollout + ROLLOUT_LABEL=attachments`, стенд вернуть; строки `REPORT.md` — замена + реплик по новым данным и память загрузки («~2 тела» → ~1,2 тела по + замеру 10.1, `MALLOC_MMAP_THRESHOLD_`), новый сценарий «Имя не в + UTF-8», если отчёт перечисляет сценарии `filename`. Проверка: + `git.dirty` в `meta.json` — `false`, код 0, ревизии до и после, сверка + записей. +- [x] 10.5 S2. `src/utils/constants.py`: `MESSAGE_TEXT_MIN_LENGTH` и + `ATTACHMENT_READ_CHUNK_BYTES` удалены (размер блока задаёт uvicorn). + Проверка: `grep` по `src/` пуст, `make lint`. +- [x] 10.6 S3. `filename` с неверным UTF-8 после процент-декодирования + (`a%FFb.png`) — 400 вместо 201 с U+FFFD: ручка строго разбирает + `scope["query_string"]`. Новый сценарий спека `attachments` «Имя не в + UTF-8» (дельта и основной спек) и тест в `test_attachments.py`. + Проверка: тест красный на коде до правки (201), зелёный после. +- [x] 10.7 S4. «Окружение не меняет лимит» (`service-configuration`): + обычный API стенда отказов запускается с `MAX_UPLOAD_BYTES=1` и + `MAX_IMAGE_PIXELS=1`, тест `fault` проверяет, что переменные заданы, и + грузит `sample.png` — 201. Проверка: `make failure_checks`. +- [x] 10.8 S5. `test_object_storage_stopped`: при остановленном S3 + история чата с `attachment_ids` — 200 (`api.all_messages`), в ней + сообщение со ссылкой на вложение. Проверка: `make failure_checks`. +- [x] 10.9 Проверки: `make lint`, `make check`, `openspec validate + attachments --type change --strict`, `openspec validate --specs`, + `make rolling_update`, `make test`, `make student_test` через LB, + `make failure_checks`. Затем отчёт и сообщение commit основной сессии. diff --git a/openspec/specs/attachments/spec.md b/openspec/specs/attachments/spec.md index e4a40dc6..0add9c6d 100644 --- a/openspec/specs/attachments/spec.md +++ b/openspec/specs/attachments/spec.md @@ -200,11 +200,25 @@ PNG — `image/png`, маркер начала JPEG — `image/jpeg`. Ответ Cf, например U+202E и U+2066); - разделители строк и абзацев U+2028 и U+2029. +Имя в строке запроса SHALL быть корректным UTF-8 после +процент-декодирования. Неверная последовательность байтов (например, +`%FF`, обрезанная или закодированный суррогат) и байт вне ASCII в +строке запроса — 400 `invalid_request`. Замена таких байтов символом +U+FFFD MUST NOT превращать отказ в принятое имя. + Принятое имя SHALL храниться и возвращаться без изменений, без обрезки и нормализации. Имя только отображается: оно MUST NOT участвовать в ключе объекта и в пути на диске. Как безопасно показать имя, решает клиент. +#### Scenario: Имя не в UTF-8 + +- **WHEN** участник загружает настоящий PNG с `filename=a%FFb.png`, + `filename=a%C3.png` и `filename=a%ED%A0%80b.png`, а затем с + `filename=%C3%A9t%C3%A9.png` +- **THEN** первые три ответа 400 `invalid_request`, последний — 201 с + `filename` `été.png` + #### Scenario: Опасное имя - **WHEN** участник загружает настоящий PNG с `filename` diff --git a/openspec/specs/db-migrations/spec.md b/openspec/specs/db-migrations/spec.md index 17c977e8..fe906538 100644 --- a/openspec/specs/db-migrations/spec.md +++ b/openspec/specs/db-migrations/spec.md @@ -126,8 +126,13 @@ - **WHEN** стенд работает на образе прежнего commit, и миграции нового образа применены, а реплики не заменены -- **THEN** `make test` и `make student_test` через LB проходят на - прежних репликах +- **THEN** проверки, которые прежний образ проходил на прежней схеме, + проходят и на новой: запись сообщений через прежние реплики — 201, + история — 200, ответов 5xx нет (замер замены реплик — + `evidence/rollout/attachments/summary.md`) +- **AND** проверки, которых прежний образ не проходил и на прежней схеме + (новые требования контракта, например вложения лабы 4 для образа лабы + 4 до `attachments`), совместимостью схемы не считаются #### Scenario: Запись прежней версии diff --git a/src/api/errors.py b/src/api/errors.py index 4352b2af..e29087e1 100644 --- a/src/api/errors.py +++ b/src/api/errors.py @@ -31,6 +31,7 @@ DOMAIN_ERRORS: dict[type[exceptions.DomainError], tuple[int, ErrorCode]] = { exceptions.AttachmentNotFound: (404, ErrorCode.NOT_FOUND), exceptions.InvalidChatMembers: (400, ErrorCode.INVALID_REQUEST), exceptions.InvalidCursor: (400, ErrorCode.INVALID_REQUEST), + exceptions.InvalidFilename: (400, ErrorCode.INVALID_REQUEST), exceptions.UploadInterrupted: (400, ErrorCode.INVALID_REQUEST), exceptions.PayloadTooLarge: (413, ErrorCode.PAYLOAD_TOO_LARGE), exceptions.UnsupportedMediaType: ( diff --git a/src/api/routers/v1/attachment.py b/src/api/routers/v1/attachment.py index 63290e2f..dc469f52 100644 --- a/src/api/routers/v1/attachment.py +++ b/src/api/routers/v1/attachment.py @@ -8,6 +8,7 @@ from collections.abc import AsyncIterator from typing import Annotated, Literal +from urllib.parse import unquote_to_bytes from fastapi import APIRouter, Query, Request from fastapi.responses import StreamingResponse @@ -25,6 +26,9 @@ from src.utils.constants import ( router = APIRouter(tags=["attachments"]) +# имя параметра имени файла в строке запроса, байтами: проверка кодировки +_FILENAME_PARAM = b"filename" + _BINARY = {"schema": {"type": "string", "format": "binary"}} # тело загрузки — сырые байты, параметра тела у ручки нет (FastAPI его не # читает): схему для /openapi.json и /docs задаём как в контракте @@ -59,6 +63,28 @@ def _media_type(request: Request) -> str | None: return value.split(";", 1)[0].strip().lower() or None +def _check_filename_encoding(request: Request) -> None: + """`filename` в строке запроса — строгий UTF-8, иначе 400. + + Starlette декодирует процент-коды с заменой неверных байтов на + U+FFFD, и `a%FFb.png` прошёл бы как `a\\ufffdb.png`. Здесь те же пары + (`&`, `=`, `+` — пробел), что у `parse_qsl`, но байты значения + проверяются строго: байт вне ASCII в строке запроса (URI его не + допускает) или неверная последовательность UTF-8 — `InvalidFilename`. + Для принятых значений результат совпадает с разбором Starlette. + """ + for pair in request.scope["query_string"].split(b"&"): + name, _, value = pair.partition(b"=") + if unquote_to_bytes(name.replace(b"+", b" ")) != _FILENAME_PARAM: + continue + if not value.isascii(): + raise exceptions.InvalidFilename + try: + unquote_to_bytes(value.replace(b"+", b" ")).decode("utf-8") + except UnicodeDecodeError as e: + raise exceptions.InvalidFilename from e + + def _content_length(request: Request) -> int | None: value = request.headers.get("content-length") return int(value) if value is not None and value.isdigit() else None @@ -91,7 +117,10 @@ async def upload_attachment( Тело не читается, пока не пройдены вход, параметры, членство, `Content-Type` и `Content-Length` (спек «Порядок проверок загрузки»). + Кодировка `filename` проверяется здесь, до членства: это 400 + параметров, как и остальные правила имени. """ + _check_filename_encoding(request) attachment = await attachments.upload( chat_id=chat_id, owner_id=user.id, diff --git a/src/core/exceptions/__init__.py b/src/core/exceptions/__init__.py index 3708c219..d3eb6e98 100644 --- a/src/core/exceptions/__init__.py +++ b/src/core/exceptions/__init__.py @@ -1,6 +1,7 @@ from .attachment import ( AttachmentContentMissing, AttachmentNotFound, + InvalidFilename, PayloadTooLarge, UnsupportedMediaType, UploadInterrupted, @@ -23,6 +24,7 @@ __all__ = [ "InvalidChatMembers", "InvalidCredentials", "InvalidCursor", + "InvalidFilename", "ObjectStorageUnavailable", "PayloadTooLarge", "ServiceUnavailable", diff --git a/src/core/exceptions/attachment.py b/src/core/exceptions/attachment.py index 28348ff5..b617e1be 100644 --- a/src/core/exceptions/attachment.py +++ b/src/core/exceptions/attachment.py @@ -23,6 +23,13 @@ class UnsupportedMediaType(DomainError): default_message = "Unsupported media type" +class InvalidFilename(DomainError): + """`filename` в строке запроса — не UTF-8 после процент-декодирования + или с байтами вне ASCII (остальные правила имени — схема API).""" + + default_message = "Filename is not valid UTF-8" + + class UploadInterrupted(DomainError): """Клиент оборвал передачу тела загрузки.""" diff --git a/src/core/services/attachment.py b/src/core/services/attachment.py index de1a3eb8..5bb02136 100644 --- a/src/core/services/attachment.py +++ b/src/core/services/attachment.py @@ -1,4 +1,5 @@ import hashlib +import io import time from collections.abc import AsyncIterator, Callable from contextlib import AbstractAsyncContextManager, AsyncExitStack @@ -190,22 +191,29 @@ class AttachmentService: body: AsyncIterator[bytes], log: AbstractLogger, ) -> bytes: - """Тело целиком; больше лимита — 413 сразу, без дочитывания.""" - buffer = bytearray() + """Тело целиком; больше лимита — 413 сразу, без дочитывания. + + Блоки копятся в `BytesIO`, а `getvalue()` отдаёт `bytes` над его + же буфером, без копии: в памяти одно тело и блок чтения (спек + «Лимит размера до чтения тела»). Именно `bytes`, а не + `bytearray`: botocore оборачивает тело `PutObject` в `BytesIO`, и + `bytes` он не копирует, а `bytearray` копирует. Рост буфера без + копии в образе даёт `MALLOC_MMAP_THRESHOLD_` (`Dockerfile`; + design, решение 6). + """ + buffer = io.BytesIO() + size = 0 try: async for chunk in body: - if len(buffer) + len(chunk) > ATTACHMENT_MAX_BYTES: - log.info( - "Rejected attachment", - reason="size", - size=len(buffer) + len(chunk), - ) + size += len(chunk) + if size > ATTACHMENT_MAX_BYTES: + log.info("Rejected attachment", reason="size", size=size) raise exceptions.PayloadTooLarge - buffer += chunk + buffer.write(chunk) except exceptions.UploadInterrupted: log.info("Rejected attachment", reason="interrupted") raise - return bytes(buffer) + return buffer.getvalue() async def get_attachment( self, diff --git a/src/utils/constants.py b/src/utils/constants.py index 4f58e474..bd67ce14 100644 --- a/src/utils/constants.py +++ b/src/utils/constants.py @@ -56,10 +56,9 @@ CHAT_MEMBERS_MIN = 1 CHAT_MEMBERS_MAX = 100 # сообщение -# пустой текст допустим только вместе с вложением: правило — в сервисе и -# схеме API, CHECK в БД — только верхняя граница (design change -# `attachments`, решение 3) -MESSAGE_TEXT_MIN_LENGTH = 1 +# нижней границы нет: пустой текст допустим только вместе с вложением, +# правило — в схеме API, CHECK в БД — только верхняя граница (design +# change `attachments`, решения 3 и 8) MESSAGE_TEXT_MAX_LENGTH = 4000 MESSAGE_ATTACHMENTS_MAX = 10 @@ -80,8 +79,6 @@ OBJECT_KEY_MAX_BYTES = 1024 # ключ объекта: `<имя базы>/attachments//original` ATTACHMENT_KEY_PREFIX = "attachments" ATTACHMENT_ORIGINAL_SUFFIX = "original" -# блок чтения тела загрузки не больше этого, байты -ATTACHMENT_READ_CHUNK_BYTES = 64 * 1024 # пагинация PAGE_LIMIT_MIN = 1 diff --git a/src/utils/image.py b/src/utils/image.py index 6e9e8ee2..b54aa96f 100644 --- a/src/utils/image.py +++ b/src/utils/image.py @@ -15,7 +15,8 @@ суммы. Память не зависит от числа пикселей: IDAT распаковывается блоками не -больше `_INFLATE_OUT_BYTES`, а вход подаётся кусками `_INFLATE_IN_BYTES`. +больше `_INFLATE_OUT_BYTES` и не дальше ожидаемого объёма плюс байт, а +вход подаётся кусками `_INFLATE_IN_BYTES`. Строки проверяются срезом с шагом длины строки, конец данных скана JPEG ищет регулярное выражение — оба в C, без цикла Python по строкам и байтам. Только stdlib, без логов: бросает свои исключения, сервис @@ -181,8 +182,15 @@ class _IdatStream: def _inflate(self, piece: memoryview | bytes) -> None: while True: + # не дальше ожидаемого объёма: «бомбу» выдаёт первый лишний + # байт, а не блок; больше ожидаемого `_check_rows` не пустит, + # поэтому предел не меньше 1 + max_length = min( + _INFLATE_OUT_BYTES, + self._expected - self._total + 1, + ) try: - out = self._inflater.decompress(piece, _INFLATE_OUT_BYTES) + out = self._inflater.decompress(piece, max_length) except zlib.error as e: raise DamagedImage("broken image data stream") from e self._check_rows(out) @@ -190,7 +198,7 @@ class _IdatStream: return piece = self._inflater.unconsumed_tail # вход кончился, а выход не упёрся в предел — буфер пуст - if not piece and len(out) < _INFLATE_OUT_BYTES: + if not piece and len(out) < max_length: return def _check_rows(self, out: bytes) -> None: diff --git a/student-tests/run_failures.py b/student-tests/run_failures.py index 846dde34..06293031 100644 --- a/student-tests/run_failures.py +++ b/student-tests/run_failures.py @@ -4,8 +4,10 @@ с override `student-tests/failures.compose.yml`: свои PostgreSQL, Valkey и S3 со своими volumes, порты хранилищ не публикуются. Затем: - собирает образ из рабочего дерева, применяет миграции и bootstrap S3; -- запускает два контейнера API: обычный и «тесный» (сроки сессии и ключа - идемпотентности 2 с, пул из одного соединения); +- запускает два контейнера API: обычный (с `MAX_UPLOAD_BYTES=1` и + `MAX_IMAGE_PIXELS=1` в окружении — лимиты вложений от них не зависят) и + «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного + соединения); - прогоняет тесты с маркером `fault` (`pytest -m fault`), передав им hook `student-tests/fault_hook.py`; - после тестов читает журнал PostgreSQL стенда: печатает сводку и падает @@ -61,6 +63,15 @@ TIGHT_ENV = { "DATABASE__POOL_TIMEOUT_SECONDS": "1", "DATABASE__REQUEST_TIMEOUT_SECONDS": "2", } +# обычный API: имена лимитов skeleton с заведомо малыми значениями. Лимиты +# вложений — константы контракта, и окружение их не меняет (спек +# `service-configuration`, «Окружение не меняет лимит»): тест грузит +# `sample.png` и ждёт 201. Те же пары тест получает в +# `FAULT_LIMITS_ENV` и сверяет, что стенд запущен с ними +LIMITS_ENV = { + "MAX_UPLOAD_BYTES": "1", + "MAX_IMAGE_PIXELS": "1", +} def say(message: str) -> None: @@ -284,7 +295,7 @@ def main() -> int: "s3-bootstrap", ) say("start api containers") - base_url = start_api(project, default_name, free_port(), {}) + base_url = start_api(project, default_name, free_port(), LIMITS_ENV) tight_url = start_api(project, tight_name, free_port(), TIGHT_ENV) say(f"ready: api={base_url} tight={tight_url}") env = ( @@ -294,6 +305,9 @@ def main() -> int: "FAULT_TIGHT_BASE_URL": tight_url, "FAULT_HOOK": str(FAULT_HOOK), "FAULT_PROJECT": project, + "FAULT_LIMITS_ENV": " ".join( + f"{key}={value}" for key, value in LIMITS_ENV.items() + ), } | storage_names(project) ) diff --git a/student-tests/test_attachments.py b/student-tests/test_attachments.py index da85cce9..0b0c6c43 100644 --- a/student-tests/test_attachments.py +++ b/student-tests/test_attachments.py @@ -15,7 +15,7 @@ from typing import Any import pytest import images -from api_client import Actor, Api +from api_client import API, Actor, Api from contract import ( BEARER_CHALLENGE, assert_content, @@ -351,6 +351,44 @@ def test_dangerous_filename( ) +@pytest.mark.spec("attachments", "Имя не в UTF-8") +def test_filename_not_utf8( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Процент-коды `filename` идут в строке запроса как есть: httpx их + не перекодирует. Без строгого разбора `a%FFb.png` давал 201 с U+FFFD + в имени вместо байта.""" + data = images.sample_png() + path = f"{API}/chats/{chat['id']}/attachments" + + def upload(query: str) -> Any: + return api.request( + "POST", + f"{path}?{query}", + actor=alice, + headers={"Content-Type": "image/png"}, + content=data, + ) + + assert_errors( + { + "invalid byte": upload("filename=a%FFb.png"), + "truncated sequence": upload("filename=a%C3.png"), + "encoded surrogate": upload("filename=a%ED%A0%80b.png"), + }, + 400, + ) + # верный UTF-8 в процент-кодах — то же имя, что прислано + attachment = assert_ok( + upload("filename=%C3%A9t%C3%A9.png"), + 201, + "Attachment", + ) + assert attachment["filename"] == "été.png" + + def assert_name_kept( api: Api, actor: Actor, diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py index e3d398b5..50bf9fb4 100644 --- a/student-tests/test_failures.py +++ b/student-tests/test_failures.py @@ -1,12 +1,14 @@ """Проверки отказов: выполняет только `make failure_checks` (маркер `fault`). Стенд и hook готовит `student-tests/run_failures.py`: свои Postgres, -Valkey и S3, обычный API (`BASE_URL`) и «тесный» (сроки сессии и ключа +Valkey и S3, обычный API (`BASE_URL`, с `MAX_UPLOAD_BYTES=1` и +`MAX_IMAGE_PIXELS=1` в окружении) и «тесный» (сроки сессии и ключа идемпотентности 2 с, пул из одного соединения). На хранилища тесты действуют только через фикстуру `stand` (hook `student-tests/fault_hook.py`) и всегда возвращают их в рабочее состояние. Решение 4 design change `failure-checks`. """ +import os import statistics import threading import time @@ -648,12 +650,16 @@ def test_object_storage_stopped( "Attachment", ) assert meta == attachment - api.send_message( + message = api.send_message( bob, chat["id"], "", attachment_ids=[attachment["id"]], ) + # история с attachment_ids — из PostgreSQL, S3 ей не нужен + history = api.all_messages(alice, chat["id"]) + assert [item["id"] for item in history] == [message["id"]] + assert history[0]["attachment_ids"] == [attachment["id"]] assert_ok(api.request("GET", "/health/ready"), 200, "Health") assert_content( api.attachment_content(bob, attachment["id"]), @@ -662,6 +668,27 @@ def test_object_storage_stopped( ) +def test_environment_does_not_change_limits( + api: Api, + alice: Actor, + chat: dict[str, Any], +) -> None: + """Спек `service-configuration`, «Окружение не меняет лимит» (вне + сверки покрытия — сценарий в докстринге): обычный API стенда + отказов запущен с `MAX_UPLOAD_BYTES=1` и `MAX_IMAGE_PIXELS=1` + (`run_failures.py`, `LIMITS_ENV`), а `sample.png` (111 817 байт, + 64 000 пикселей) всё равно принимается: лимиты — константы.""" + limits = dict( + item.split("=", 1) + for item in os.environ.get("FAULT_LIMITS_ENV", "").split() + ) + # без этих переменных на стенде тест ничего не доказывает + assert limits == {"MAX_UPLOAD_BYTES": "1", "MAX_IMAGE_PIXELS": "1"}, ( + f"stand started without limit variables: {limits}" + ) + api.upload(alice, chat["id"], images.sample_png(), filename="sample.png") + + @pytest.mark.spec("attachments", "S3 завис") def test_object_storage_paused( api: Api,