Files
mtusi2026lab4/openspec/changes/fix-upload-put-flake/proposal.md
T
2026-10-22 22:52:59 +03:00

98 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Proposal
## Why
`make student_test` через LB изредка красный: на исправном S3 загрузка
вложения получает 503 (`KNOWN_ISSUES.md`, «Изредка 503 на загрузке: PUT
в S3 обрывается без тела», три из восьми прогонов 2026-10-22). Проба этого
change нашла причину (design, Context):
- клиент S3 включает срок чтения aiohttp (`read_timeout` = `[s3]
timeout_seconds`, 5 с);
- после скачивания большого оригинала aiohttp 3.13–3.14.5 оставляет этот
срок взведённым у соединения, которое уже вернулось в пул;
- через 5 с простоя срок срабатывает на простаивающем соединении и
ломает его;
- следующий вызов S3 на этом соединении, если он пришёл до конца
keep-alive (15 с), падает за 1 мс с `ReadTimeoutError`. S3 получает
заголовки PUT без тела, клиент — 503.
Это не регрессия `upload-memory`: образ `f894040` с телом `bytes` даёт тот
же отказ. В наборе дефект проявился после `test_concurrent_uploads`
(10 скачиваний по 1 MiB, затем ≥ 5 с без вызовов S3 на реплике). Клиент
контракта получает 503, хотя S3 исправен, и загрузку приходится
повторять.
## What Changes
- Срок клиента S3 — только срок приложения на каждый вызов и на каждый
блок чтения (`asyncio.timeout([s3] timeout_seconds)`, как сейчас).
Собственный срок чтения aiohttp выключается: таймера, который
переживает ответ и ломает соединение в пуле, больше нет. Пул
keep-alive, путь PUT (одна копия тела), сроки, отказ без повторов и
перевод ошибок в 503 — прежние.
- Правило «S3 без повторов» (`infra.md`) не меняется: повтора нет, причина
убрана, а не скрыта.
- Тест на стенде отказов, красный до кода:
- четвёртый API с коротким сроком вызова S3 (1 с);
- на нём раунды: одновременные медленные скачивания оригинала в
несколько MiB, простой дольше срока, затем загрузки — каждая 201.
- Команда драйвера скилла `driver.py s3-idle`: проба клиента в реплике
API стенда — у варианта образа и у эталона с прежним сроком чтения.
Она показывает, сколько соединений после скачиваний взведено, сколько
испорчено после простоя и чем кончились следующие PUT.
- Evidence механизма и правки:
- вывод `s3-idle` до и после замены реплик;
- захват пакетов падающего PUT и воспроизведение по HTTP из пробы
этого change, тот же отказ на `f894040`;
- `make student_test` подряд без 503, `make failure_checks`;
- точечная проба памяти PUT и `make bench_uploads_quick` — одна копия
тела сохраняется.
- Запись `KNOWN_ISSUES.md` удаляется. `REPORT.md` и правила (`infra.md`,
`student-tests.md`) описывают сроки клиента и новый API стенда
отказов.
Не входит: `track2-reconcile-cost`, отчёт и PR, остальные записи
`KNOWN_ISSUES.md`, отчёт об ошибке в aiohttp. Новых настроек, миграций и
изменений контракта нет.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `object-storage`: в «Клиенте хранилища в приложении» срок вызова —
единственный срок клиента. Соединение в пуле не хранит срока прошлого
вызова, и вызов после простоя дольше срока проходит.
- `attachments`: в «Недоступности S3» 503 — только при отказе S3, а не
после простоя исправного S3; новый сценарий «Загрузка после простоя
S3».
- `student-tests`: в «Проверках отказов на отдельном стенде» — четвёртый
API с коротким сроком вызова S3 и новый сценарий в списке проверок
отказов `attachments`.
## Impact
- Код: `src/infra/s3/client.py` (`_create_client`: срок чтения
aiohttp выключен, докстринг). Повторов, настроек и путей ответа это не
добавляет.
- Тесты: `student-tests/test_failures.py` (новый тест),
`student-tests/run_failures.py` (четвёртый API и его окружение
тестам), `student-tests/conftest.py` (фикстура и проверка адреса),
`student-tests/api_client.py` (медленное скачивание потоком).
- Драйвер скилла `run-mtusi-messenger`: команда `s3-idle` и её раздел в
`SKILL.md`.
- Документы: `.claude/rules/infra.md`, `student-tests.md`; AGENTS.md;
`REPORT.md`; `KNOWN_ISSUES.md`; `PLAN.md`.
- Evidence: `evidence/s3/idle-connection.md`, `evidence/tests/` —
`failure-checks.md` и `student-test-lb.md`.
- Стенд: новый образ API и уборщика — `make rolling_update`, затем
`docker compose up -d --no-deps cleaner`. Схема и bootstrap не меняются.
- Регресс: `make failure_checks` (+1 проверка, ~+20 с), `make
student_test`, `make test_isolated`, `make bench_uploads_quick`, точечная
проба памяти PUT, `make test-persistence`. Метку
`evidence/uploads/baseline/` путь PUT не затрагивает. Нужна ли её
пересъёмка — вопрос пользователю (design, решение 5).