docs: propose fix-upload-put-flake

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-22 22:52:59 +03:00
co-authored by Claude Opus 5.5
parent b804cec625
commit 7d4b2cb37e
8 changed files with 992 additions and 0 deletions
+88
View File
@@ -1290,3 +1290,91 @@ SeaweedFS и PostgreSQL на tmpfs, bootstrap проекта.
`test_reconcile_keeps_fresh_used_and_unknown`,
`test_reconcile_restored_original`, шаги 5–6 и 8 `driver.py
reconcile-cycle`, правило `api-contract.md`.
### fix-upload-put-flake
Change вне сводной таблицы, до `track2-reconcile-cost`: исправление
записи `KNOWN_ISSUES.md` «Изредка 503 на загрузке: PUT в S3 обрывается
без тела» (решение пользователя 2026-10-22).
#### Решения
Приняты 2026-10-22 в `/opsx:propose`, подробности — design change
`fix-upload-put-flake`. Пробы — design, Context: временный проект compose
`upfprobe` (тот же `docker-compose.yml`, синтетические секреты, данные S3
— volume `upfprobe_s3_data`, удалён после пробы), образы текущего дерева,
`f894040` и прототипа правки.
1. **Причина найдена и воспроизведена** (design, Context):
- клиент S3 задаёт aiohttp срок чтения (`read_timeout` = `[s3]
timeout_seconds`, 5 с, с `s3-storage`);
- после скачивания большого оригинала (больше буфера ответа 128 KiB)
aiohttp 3.13–3.14.5 перевзводит этот срок в `resume_reading()` уже
после конца ответа, когда соединение вернулось в пул;
- через 5 с простоя срок срабатывает и портит соединение: исключение
сохранено, транспорт открыт;
- пул отдаёт его следующему вызову в окне 5–15 с (keep-alive), и вызов
падает за 1 мс — `ReadTimeoutError` → 503. S3 видит заголовки без
тела: botocore ставит `Expect: 100-continue` любому телу PutObject.
Подтверждено:
- журнал рабочего стенда: три 503 через 5,9–6,8 с после скачиваний
`test_concurrent_uploads` на той же реплике;
- локальная проба aiohttp и проба клиента в образе API;
- HTTP через LB: до 13 × 503 за 4 раунда;
- захват пакетов: FIN клиента через 0,1 мс после заголовков PUT, 0 байт
тела.
Полный `make student_test` на пробном стенде — 10 прогонов из 10
зелёные: вероятность отказа на прогон зависит от таймингов. Поэтому
доказательство — целевое воспроизведение.
2. **Не регрессия `upload-memory`**: образ `f894040` (тело `bytes`) — 8 ×
503 в 4 раундах из 5 с той же подписью. В набор триггер пришёл с
`test_concurrent_uploads` (10 скачиваний по 1 MiB, затем ≥ 5 с без
вызовов S3).
3. **Правка — `read_timeout=None`** (решение 1). Срок вызова и блока
чтения — `asyncio.timeout` приложения, как было. Прототип в раундах
теста: 0 отказов из 120 загрузок после простоя, а на текущем образе в
тех же раундах — 17 × 503 (испорчено 17 соединений из 60). 503 при
`docker pause` S3 — за 5,02 с; обрыв ответа посреди тела — через 5,9 с.
Отвергнуты:
- `force_close`;
- связка сроков keep-alive и `sock_read`;
- свой коннектор и патч aiohttp;
- другая версия aiohttp: дефект в 3.13.5–3.14.5, aiobotocore 3.9.2
требует ≥ 3.14.0;
- снятие `Expect`;
- больший буфер ответа;
- повтор.
4. **Правило «S3 без повторов» не меняется** (решение 2): повтор лечил бы
симптом, а `ReadTimeoutError` порчи не отличить от таймаута зависшего S3
без закрытых полей aiohttp.
5. **Тест — стенд отказов, четвёртый API с `S3__TIMEOUT_SECONDS=1`**
(решение 3): до 8 раундов «10 одновременных медленных скачиваний ~4 MiB
→ простой 1,5 с → 12 загрузок». Вероятность промаха на прежнем коде ≈
4e-12, `make failure_checks` дольше на ~20 с. В `make student_test` не
кладётся: раунд там — 6+ с простоя, нужно ~5 раундов (+35 с), и тест
всё равно вероятностный. Hook с пробой клиента в контейнере отвергнут:
это импорт `src` в обход HTTP.
6. **Evidence механизма — `driver.py s3-idle`** (решение 4): проба
клиента в реплике стенда, вариант образа против эталона с прежним
сроком. Файл — `evidence/s3/idle-connection.md`.
7. **Путь PUT не меняется** (решение 5): то же тело, заголовки, соединение
и срок. Проба памяти PUT 10 MiB на прототипе — 1,18 тела против 1,19.
#### Вопросы
1. Нужна ли пересъёмка полной метки `make bench_uploads`
(`evidence/uploads/baseline/`)?
- Правка путь PUT не меняет: то же тело, те же заголовки, то же
соединение из пула, тот же срок вызова. Исчезает только взвод таймера
`sock_read` после записи тела.
- Профиль `uploads` только загружает и не скачивает, порча соединений в
метке не возникала (design, решение 5).
- По мнению агента пересъёмка не нужна: хватит точечной пробы памяти и
`make bench_uploads_quick` в apply (tasks 4.4).
- Полный прогон (~50 мин) требует тихого хоста, а на нём сейчас
работают контейнеры другого проекта. Решение — за пользователем.
По умолчанию до ответа — не переснимать, метка `baseline` остаётся.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-22
@@ -0,0 +1,390 @@
# Design
## Context
Симптом и масштаб — proposal.md, «Why», и запись `KNOWN_ISSUES.md`. Здесь
— механизм, как он подтверждён, и проверенные гипотезы. Пробы —
2026-10-22, временный проект compose `upfprobe`:
- тот же `docker-compose.yml`, свой env-файл с синтетическими секретами и
копия `config_example.toml`;
- образ — `mtusi-messenger:upfprobe` из рабочего дерева `b804cec`, то же
API, что `c1648d9` на рабочем стенде;
- LB на `127.0.0.1:18090`, PostgreSQL в tmpfs, данные S3 — в volume
`upfprobe_s3_data`.
Скрипты проб — в scratchpad сессии. Рабочий стенд — только чтение
журналов.
### Механизм (aiohttp 3.14.5, aiobotocore 3.9.2, botocore 1.43.106)
1. Клиент S3 задаёт aiohttp срок чтения сокета: `read_timeout=[s3]
timeout_seconds` (5 с) → `ClientTimeout(sock_read=5)`
(`src/infra/s3/client.py`, `_create_client`; так с `s3-storage`,
`2e997f9`). Это второй срок поверх `asyncio.timeout` каждого вызова и
блока чтения.
2. Скачивание объекта больше буфера потока aiohttp (64 KiB, порог паузы
— 128 KiB) идёт с паузами чтения: буфер ответа переполнился, парсер
встаёт на паузу.
3. Иногда конец тела парсер разбирает уже внутри
`ResponseHandler.resume_reading()`, когда потребитель освободил буфер.
Тогда:
- конец ответа отпускает соединение в пул (`_response_eof` →
`Connection.release()`);
- после этого тот же `resume_reading()` снова взводит срок чтения
(`_reschedule_timeout()`): у соединения в пуле остаётся таймер на
5 с.
4. Простой дольше 5 с: таймер срабатывает на простаивающем соединении
(`_on_read_timeout`). Протокол получает исключение `SocketTimeoutError`
и признак конца, но транспорт открыт: `is_connected()` — истина.
5. Пул aiohttp отдаёт соединения по порядку возврата (`popleft`, первым
— самое давнее). Проверяет он только `is_connected()` и keep-alive
(15 с), но не сохранённое исключение (`TCPConnector._get`). Так
испорченное соединение достаётся следующему вызову, пришедшему в окно
5–15 с после скачивания.
6. Вызов отправляет заголовки, а `protocol.read()` сразу бросает
сохранённое исключение. aiohttp закрывает соединение, aiobotocore
переводит `ServerTimeoutError` в `ReadTimeoutError`, клиент проекта —
в `ObjectStorageUnavailable`, и клиент получает 503 за 1 мс.
7. Почему S3 видит «got 0 bytes»: botocore превращает тело PutObject из
`bytes` в `BytesIO` (`convert_body_to_file_like_object`). Любому
телу с `read` он ставит `Expect: 100-continue` (`add_expect_header`).
aiohttp ждёт «100 Continue» и до ошибки тела не шлёт. SeaweedFS
начинает читать тело и получает EOF.
Сброс таймера при следующем вызове (`start_timeout()` отменяет прежний)
объясняет окно: вызов раньше 5 с проходит, позже 15 с — получает новое
соединение. Версии: в aiohttp 3.13.5 и 3.14.0 `resume_reading()`
перевзводит срок безусловно, в 3.14.4–3.14.5 — после паузы. 3.14.5 —
последняя версия на PyPI, aiobotocore 3.9.2 требует `aiohttp>=3.14.0`.
Отчёта об этом дефекте в aiohttp не нашлось (поиск 2026-10-22).
### Как подтверждено
1. **Журнал рабочего стенда** (реплика `151df4af59c3`). Каждому из трёх
503 (18:18:30, 18:20:04, 18:22:10) за 5,9–6,8 с предшествовали:
- пять одновременных загрузок по 1 MiB и пять скачиваний этих
оригиналов на этой же реплике — `test_concurrent_uploads`, половина
его вложений;
- загрузки через 4,5 с после скачиваний проходили: таймер ещё не
сработал;
- у каждого отказа — `put_object`, `ReadTimeoutError`, `duration_ms`
1, в журнале S3 — «got 0 bytes».
2. **Локальная проба aiohttp** (сервер aiohttp.web на loopback,
`sock_read=1`, asyncio и uvloop). GET 1 MiB с потребителем медленнее
сети (2 мс на блок 64 KiB):
- соединение в пуле со взведённым сроком;
- через 1,5 с простоя у него `SocketTimeoutError`, `connected=True`;
- следующий PUT — «Timeout on reading data from socket» за 1,2–2,0 мс;
- с `Expect: 100-continue` сервер получает сброс соединения на чтении
тела.
Быстрый потребитель (без паузы) таймера не оставляет.
3. **Клиент проекта в образе API** (uvloop, S3 пробного стенда):
- по 10 скачиваний подряд: объекты 64, 120 и 200 KiB — 0 из 90
взведённых соединений; 1 MiB — 0–2 из 10; 10 MiB — 1–6 из 10;
- раунды по 10 одновременных скачиваний (10 раундов): 1 MiB — 57–81
соединений из 100; 4 MiB при потребителе 0,5 мс на блок — 95–99 из
100;
- сквозной пример: после 10 одновременных скачиваний по 1 MiB одно
соединение взведено, через 5,5 с оно испорчено. PUT, которому пул
отдал его девятым по очереди, — `ObjectStorageUnavailable` ←
`ReadTimeoutError` («Read timeout on endpoint URL») ←
`SocketTimeoutError` («Timeout on reading data from socket») за
1,2 мс. Остальные 11 PUT проходят;
- с `read_timeout=None` — 0 взведённых и 0 испорченных во всех тех же
прогонах, 12 из 12 PUT после простоя проходят.
4. **HTTP через LB пробного стенда**: одна реплика, срок 5 с, простой
6 с, затем 12 загрузок; ответы и журнал — как на рабочем стенде:
| Раунд (до простоя) | Раундов с 503 | 503 всего |
|---|---|---|
| 10 скачиваний 1 MiB подряд | 0 из 3 | 0 |
| то же, клиент читает медленно | 1 из 2 | 1 |
| 10 одновременных скачиваний 1 MiB | 5 из 7 | 10 |
| 10 одновременных 4 MiB | 4 из 5 | 12 |
| 10 одновременных 4 MiB, клиент медленно | 4 из 4 | 13 |
5. **Захват пакетов** (`tcpdump` в сетевом пространстве реплики, порт
8333, разбор без значений заголовков). Три упавших PUT:
- в каждом соединении последний запрос перед отказом — GET объекта
~1 MiB (ответ 200), за 6,15 с до отказа;
- затем PUT: заголовки 980 байт с `Expect: 100-continue` и
`x-amz-checksum-crc32`;
- через 0,1 мс после заголовков — FIN клиента, через 0,2–0,4 мс S3
отвечает «100 Continue», клиент — RST; тела — 0 байт.
6. **Не регрессия `upload-memory`.** Образ `f894040` (тело `bytes`)
тем же раундом (10 одновременных 1 MiB) дал 8 × 503 в 4 раундах из 5
с той же подписью. В журнале S3 — «got 0 bytes»: `Expect:
100-continue` ставится и там (п. 7 механизма).
7. **Набор целиком.** На пробном стенде две реплики, текущий образ,
`make student_test` (pytest напрямую): 10 зелёных прогонов, ни одного
отказа S3. На рабочем стенде было 3 из 8 красных. Вероятность на прогон
зависит от таймингов стенда: какие соединения в пуле, где паузы между
тестами. Поэтому доказательство — целевое воспроизведение, а не цикл
набора. Прогоны, где пробный S3 с данными в tmpfs упёрся в память
контейнера (страницы tmpfs считаются его памятью, PUT — срок 5 с,
`TimeoutError`), отброшены, и данные S3 перенесены в volume. Из 10
зелёных два сняты ещё на tmpfs, до нехватки памяти.
8. **Кандидат правки** (`read_timeout=None`, образ
`mtusi-messenger:upfprobe-fix` — один изменённый файл):
- отдельный API со сроком S3 1 с, напрямую без LB, раунды «10
одновременных медленных скачиваний 4 MiB → простой 1,5 с → 12
загрузок»: на текущем образе 6 раундов из 6 с 503 (17 из 60
соединений, p ≈ 0,28); с правкой — 0 из 120 загрузок за 10 раундов.
Подбор раунда на текущем образе: 1 MiB без медленного чтения — 503 в
1 раунде из 10; 4 MiB при 10 мс на блок — 7 из 40 соединений; 2 MiB —
8 из 40; 8 MiB — 3 из 40;
- замороженный S3 (`docker pause`): загрузка и скачивание — 503 за
5,02 с, как до правки; замороженный посреди тела ответ обрывается
через 5,9 с после заморозки (до правки — 5,5 с);
- проба памяти PUT 10 MiB (`put_memory_check.py` из `upload-memory`):
1,18 тела над базой против 1,19 до правки, путь `bytes` — 2,31,
SHA-256 объектов совпал.
### Проверенные гипотезы
| Гипотеза | Итог | Чем проверено |
|---|---|---|
| Регрессия `upload-memory`: `BytesIO` вместо `bytes` | нет | `f894040` даёт тот же отказ (Как подтверждено, п. 6) |
| Повторное использование соединения после ответа S3 с ошибкой или раннего закрытия | нет | последний обмен испорченного соединения — успешный GET 200; S3 соединение не закрывал и ответил «100 Continue» |
| Keep-alive SeaweedFS закрыл соединение | нет | S3 отвечает на PUT по тому же соединению; простой 6 с < 120 с шлюза; закрыл клиент (FIN) |
| Повтор внутри aiohttp на новом соединении с прочитанным потоком | нет | aiohttp повторяет идемпотентный запрос (PUT в том числе) один раз только на `ClientOSError` и `ServerDisconnectedError` переиспользованного соединения, перемотав тело (`ClientSession._request`). У этого отказа — `SocketTimeoutError`, повтора нет: в захвате у PUT одна попытка |
| `Expect: 100-continue` botocore | не причина | объясняет только «got 0 bytes»: тело ждёт «100 Continue» и не уходит. Без него ошибка клиента та же |
| Контрольная сумма botocore 1.43 над потоком | не причина | по HTTP сумма — заголовок, считается до отправки; отказ — раньше первого байта тела |
| Срок чтения aiohttp переживает ответ и портит соединение в пуле | **причина** | п. 2, 3, 5, 8 |
## Goals / Non-Goals
**Goals:**
- исправный S3 не даёт 503 после простоя соединений клиента;
- причина убрана, а не скрыта повтором;
- тест на стенде отказов, красный до кода с вероятностью промаха меньше
1e-9, зелёный после;
- путь PUT, одна копия тела, сроки и перевод ошибок — прежние.
**Non-Goals:**
- отчёт об ошибке и правка в aiohttp — не проект лабы. Если upstream
исправит, решение 1 не мешает: срок чтения aiohttp проекту не нужен;
- лимит одновременных скачиваний, срок отдачи тела клиенту — как было;
- прочие записи `KNOWN_ISSUES.md`.
## Decisions
### 1. Срок клиента S3 — только срок приложения; срок чтения aiohttp выключен
`_create_client` передаёт `AioConfig(read_timeout=None)`. aiobotocore
строит `ClientTimeout(sock_connect=[s3] connect_timeout_seconds,
sock_read=None)`. aiohttp таймер чтения не взводит вовсе, и в пуле нечему
сработать.
Сроки остаются:
- `asyncio.timeout([s3] timeout_seconds)` на каждый вызов (`_call`: весь
вызов botocore, в том числе чтение тела непотокового ответа);
- тот же срок на каждый блок потокового чтения (`_read_chunk`);
- `connect_timeout` (1 с).
Срок приложения начинается не позже `sock_read` и равен ему, поэтому
зависший S3 он обрывает за тот же срок. `sock_read` мог лишь опередить
его на блоке потокового чтения: он отсчитывает время от последних
данных сокета, а не от начала блока. Проба п. 8 — те же 503 за 5,02 с и
обрыв ответа посреди тела.
В `infra.md` строка «`connect_timeout_seconds` и `read_timeout` botocore
— из `[s3]`» меняется на «`read_timeout` выключен (None)». Причина и
запрет включать его без новой пробы — рядом. Из этого выводится и
правило: всякое новое чтение из S3 — внутри `_call` или `_read_chunk`, а
не голым `await` на ответе aiohttp.
*Альтернативы, отвергнутые:*
- `force_close` у коннектора (соединение на вызов). Таймер остаётся, но
соединение после вызова закрывается. Цена:
- новое TCP-соединение на каждый вызов, в том числе на каждый HEAD
сверки;
- `TIME_WAIT` у клиента;
- другой путь PUT, чем мерила метка `evidence/uploads/baseline/`.
- keep-alive короче `sock_read` (например, 4 с при 5) или `sock_read`
длиннее keep-alive (16 с при 15): испорченное соединение не доживает до
выдачи. Но таймер остаётся, а связь двух сроков неочевидна и ломается
при правке любого из них.
- Свой класс сессии (`AioConfig(http_session_cls=…)`) и коннектор,
который не отдаёт протокол с `should_close`: опора на закрытые методы
aiohttp (`_get`, `_conns`).
- Патч aiohttp (`resume_reading`): то же, плюс расходится с `uv.lock`.
- Другая версия aiohttp: дефект есть в 3.13.5 и 3.14.0–3.14.5, а
aiobotocore 3.9.2 требует ≥ 3.14.0.
- Убрать `Expect: 100-continue`: S3 получил бы тело, но клиент упал бы
так же. Объект без подтверждения потом убрал бы уборщик.
- Выключить контрольные суммы botocore: к отказу не относятся.
- Больший `read_bufsize`, чтобы пауз не было: буфер ответа держал бы
объект целиком, и память скачиваний росла бы с размером.
- Повтор (решение 2).
### 2. Повторов нет: правило «S3 без повторов» не меняется
Безопасный повтор (тело не ушло, поток с начала, срок прежний) отвергнут:
- он лечит симптом. Испорченное соединение по-прежнему выдаётся, первая
попытка по-прежнему тратит его;
- `ReadTimeoutError` ничем не отличается от настоящего таймаута после
тела. Различать их пришлось бы по закрытым полям aiohttp, иначе повтор
удвоил бы ожидание зависшего S3 сверх срока вызова;
- после решения 1 повторять нечего.
`infra.md`, `s3-storage` (решения 6–7) и спек `object-storage` («вызов
MUST NOT повторяться автоматически») остаются в силе.
### 3. Тест: четвёртый API стенда отказов с коротким сроком S3
Сценарий `attachments` «Загрузка после простоя S3» (дельта) проверяет
`test_upload_after_idle_s3` в `student-tests/test_failures.py` (маркер
`fault`). Hook не нужен: тест только ходит по HTTP. Особый стенд нужен
для срока:
- `run_failures.py` запускает четвёртый API `<проект>-api-s3` с
`S3__TIMEOUT_SECONDS=1`. До правки это и `sock_read`: простой 1,5 с
вместо 6 с;
- адрес — `FAULT_S3_BASE_URL`, окружение — `FAULT_S3_ENV`; тест сверяет
стенд с ним, как `assert_uploads_stand`;
- других тестов на этом API нет, и пул S3 процесса — только от теста.
Раунд:
1. Участник загружает PNG из шума ~4 MiB — один раз на тест.
2. 10 одновременных скачиваний этого оригинала, у каждого клиента своё
соединение и барьер. Клиент читает медленно, 2 мс на блок 64 KiB.
Каждое тело сверяется с загруженным.
3. Простой `S3__TIMEOUT_SECONDS + 0,5` с без запросов к этому API.
4. 12 загрузок `sample.png` по одной. Каждая — 201: пул отдаёт
соединения по порядку возврата, и 12 загрузок проходят через все ≤ 10
соединений пула.
До 8 раундов, тест падает на первом не-201 с номером раунда и ответом.
По пробе (Как подтверждено, п. 8) соединение портится с p ≈ 0,28. Промах
раунда — 0,72^10 ≈ 0,037, восьми раундов — ≈ 4e-12. На коде с правкой —
8 раундов ≈ 16 с, `make failure_checks` дольше на ~20 с вместе со стартом
API.
*Альтернативы:*
- Тест в `make student_test` (обычный стенд, срок 5 с). Раунд — 6+ с
простоя. Промах раунда по таблице п. 4 — от ~0,03 до ~0,3, через один
процесс без LB (`make test_isolated`) — выше (п. 8: напрямую 1 MiB дали
503 в 1 раунде из 10). Надёжность требует ~5 раундов, +35 с к набору в
38 с. Отвергнуто.
- Hook, запускающий пробу клиента в контейнере API: детерминированнее, но
это импорт `src` из теста в обход HTTP. Против правила `student-tests`.
Отвергнуто.
- Сделать запуск точно детерминированным. Порча зависит от того, где TCP
разрезал хвост ответа S3. Снаружи процесса этим не управлять ни
размером, ни темпом клиента (п. 3–4). Отвергнуто, вероятность промаха
считается и называется.
Красный прогон — до правки кода: `make failure_checks FAULT_ARGS='-k
idle_s3'` три раза подряд, каждый красный. После правки — те же три
зелёные. Оба вывода — в `evidence/tests/failure-checks.md`.
### 4. Evidence механизма: команда драйвера `s3-idle`
`driver.py s3-idle` скилла `run-mtusi-messenger` (stdlib, Python 3.9):
- запускает пробу клиента в работающей реплике API стенда (`docker exec
-i <реплика> python -`). Это код и ключи образа: ключи в драйвер не
попадают;
- два варианта клиента — как в образе и эталонный с прежним
`read_timeout=[s3] timeout_seconds`;
- в каждом: раунды по 10 одновременных медленных скачиваний объекта
4 MiB, простой `[s3] timeout_seconds + 0,5` с, 12 PUT;
- печатает по варианту: соединений взведено после скачиваний, испорчено
после простоя, PUT прошло и упало (класс ошибки и цепочка причин, время
в мс);
- объекты — под `<база>/.s3-idle-probe/`, удаляются в `finally`. Сверка
этот префикс не читает, а `attachments/` проба не трогает;
- код 0 — у варианта образа ни одного испорченного соединения и упавшего
PUT, код 1 — иначе. Эталон может падать: так команда показывает
механизм.
Счётчики берутся из закрытых полей aiohttp (`connector._conns`,
`_read_timeout_handle`, `_exception`). Это диагностика, а не код
приложения. Если полей нет (другая версия aiohttp), команда печатает
«n/a» и судит только по PUT. «S3 получает тело целиком» (сценарий
`object-storage` «Вызов после простоя») проверяется чтением каждого
записанного объекта: размер и SHA-256. Проба — отдельный процесс в
контейнере реплики: пул API она не трогает, но на время команды берёт
~100 MiB памяти и CPU реплики, поэтому запускается без нагрузки на стенд.
Evidence `evidence/s3/idle-connection.md`:
- механизм из Context с номерами строк aiohttp 3.14.5;
- вывод `driver.py s3-idle` на рабочем стенде до и после замены реплик;
- сводка захвата пакетов и таблица HTTP-раундов из пробы propose;
- сравнение с `f894040`.
Подписи, ключи и значения заголовков в evidence не попадают.
### 5. Путь PUT, одна копия тела и метка `uploads`
Правка не трогает путь PUT:
- то же тело (`BytesIO` после `del data`) и те же заголовки (`Expect`,
CRC32, подпись);
- то же соединение из пула keep-alive и тот же срок вызова.
Исчезает только взвод таймера `sock_read` после записи тела. Профиль
`uploads` (`bench/k6/uploads.js`) только загружает и не скачивает: порча
соединений в метке `evidence/uploads/baseline/` не возникала, и
измеренный путь — ровно этот.
Мнение агента: пересъёмка полного `make bench_uploads` не нужна. Проверка
— точечная проба памяти PUT в образе с правкой (на прототипе 1,18 тела,
до правки 1,19) и `make bench_uploads_quick` (самопроверка, метка
`quick-*`, в git не идёт). Нужна
ли пересъёмка полной метки на тихом хосте — решает пользователь
(`PLAN.md`, `### fix-upload-put-flake`, «Вопросы», п. 1). До ответа метка
`baseline` остаётся.
### 6. Документы
- `.claude/rules/infra.md`, раздел S3: срок клиента — только
`asyncio.timeout`, `read_timeout` выключен и почему; новое чтение из S3
— только через `_call` и `_read_chunk`.
- `.claude/rules/student-tests.md` и AGENTS.md (карта кода,
`run_failures.py`): четвёртый API стенда отказов и тест.
- `REPORT.md`:
- клиент S3 — сроки;
- строка в «Эксперименты и отказы»;
- строка `make student_test` в таблице доказательств — без оговорки о
503;
- в «Ограничениях» — дефект aiohttp и почему проекту не нужен его срок
чтения.
- `KNOWN_ISSUES.md`: запись удаляется, история — в git.
- `evidence/tests/student-test-lb.md`: раздел «Повторные прогоны»
дополняется исходом — причина и восемь прогонов после замены реплик.
## Risks / Trade-offs
- [Без `sock_read` чтение вне `asyncio.timeout` зависло бы без срока] →
все чтения клиента уже внутри `_call` и `_read_chunk`. Правило `infra.md`
закрепляет это для новых. Отказы «S3 завис» (`make failure_checks`) и
проба п. 8 проверяют срок.
- [botocore считает TTL повтора из `read_timeout`] → после успешного
непотокового ответа `_set_ttl` с `None` бросает `TypeError` и сам его
ловит, запись на `debug`. Логгер botocore стоит на WARNING (`logging.md`),
повторов нет (`total_max_attempts=1`), поэтому TTL не используется.
Цена — микросекунды на вызов.
- [Тест вероятностный внутри раунда] → вероятность промаха 8 раундов
≈ 4e-12 по замеру, названа в тесте и evidence. Красный прогон — три раза
подряд.
- [Новый aiohttp вернёт похожий дефект в другом месте] → срок чтения
aiohttp не используется вовсе, а тест и `driver.py s3-idle` ловят порчу
соединения при простое по поведению.
- [Смесь версий при `make rolling_update`] → старые реплики до замены
могут дать тот же 503. Данные он не портит: строка `pending` уходит
уборщику. Новый код уборщика — `docker compose up -d --no-deps cleaner`.
- [Четвёртый API на стенде отказов] → +1 контейнер (~2 с старта) и +~20 с
прогона. Порты — только `127.0.0.1`, уборка — вместе с остальными.
## Migration Plan
1. Код и тест — одним commit. Вперёд: `make rolling_update` (миграций
нет), затем `docker compose up -d --no-deps cleaner`.
2. Bootstrap S3, схема, `.env` и `config.toml` не меняются.
3. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0` и прежний образ
уборщика. Прежний код снова изредка даёт 503, данные целы.
## Open Questions
Нет. Пересъёмка метки `uploads` — вопрос пользователю (решение 5), план
и задачи от ответа не зависят.
@@ -0,0 +1,97 @@
# 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).
@@ -0,0 +1,46 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Недоступность S3
Если S3 недоступен, не ответил за срок вызова или отказал
(`object-storage`), загрузка и скачивание байтов SHALL отвечать 503
`unavailable` в формате ошибки. Ответ SHALL приходить не позже срока
вызова S3 с запасом, а не 500 и не зависанием. Без S3 SHALL работать:
- метаданные вложения;
- история чата с `attachment_ids`;
- отправка сообщений, в том числе со ссылкой на готовое вложение;
- `/health/ready`.
После возврата S3 загрузка и скачивание SHALL проходить без перезапуска
API.
503 на загрузке и скачивании SHALL означать только такой отказ S3:
недоступен, не ответил за срок или отказал. Доступный S3 MUST NOT давать
503 из-за того, что реплика какое-то время не обращалась к нему, в том
числе после скачивания больших оригиналов.
#### 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
#### Scenario: Загрузка после простоя S3
- **WHEN** участники одновременно скачали оригинал в несколько MiB,
затем реплика дольше срока вызова S3 не обращалась к S3, а S3 всё это
время доступен, и участник одну за другой загружает файлы
- **THEN** каждая загрузка — 201, ни одной 503
- **AND** скачанные байты совпадают с загруженными
@@ -0,0 +1,93 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Клиент хранилища в приложении
Процессы приложения SHALL обращаться к S3 с учётными данными своей роли
из секции `[s3]`: реплики API — ключами пользователя API, уборщик —
ключами пользователя уборщика. Клиент SHALL уметь:
- записать объект;
- прочитать его потоком;
- получить метаданные;
- удалить объект;
- перечислить объекты с заданным префиксом страницами, с размером и
временем изменения каждого объекта.
Удаление отсутствующего объекта — не ошибка. Каждый вызов, в том числе
каждая страница списка, SHALL быть ограничен сроком из настроек. После
отказа или истечения срока вызов MUST NOT повторяться автоматически.
Срок из настроек SHALL быть единственным сроком вызова, и он
заканчивается вместе с вызовом: у потокового чтения он действует на
каждый блок. Соединение, которое простаивает в пуле клиента, MUST NOT
ломаться от срока прошлого вызова. Поэтому вызов после простоя S3 дольше
срока вызова SHALL проходить, если S3 доступен, — в том числе после
потокового чтения большого объекта. Ошибкой недоступности такой вызов
SHALL заканчиваться только по причинам из списка ниже.
Ошибкой недоступности, которую API отдаёт как 503 `unavailable` в
формате контракта, SHALL заканчиваться вызов, если S3:
- недоступен;
- не ответил за срок;
- отклонил учётные данные;
- отказал ключу в доступе или не нашёл bucket.
Такой вызов MUST NOT давать 500 или зависать. Отсутствующий объект SHALL
отличаться от недоступности. Отсутствующий bucket MUST NOT выдаваться
за отсутствующий объект у записи, чтения, удаления и списка: список без
bucket — ошибка, а не пустая страница. После возврата S3 вызовы SHALL
проходить без перезапуска приложения. Соединения с S3 SHALL открываться
при первом вызове, а при остановке сервиса клиент SHALL закрываться.
Ключ объекта SHALL начинаться с имени базы PostgreSQL процесса и `/`.
Так объекты прогона на временной базе (`make test_isolated`) отделены
от объектов рабочей базы.
#### Scenario: S3 остановлен
- **WHEN** S3 остановлен, и приложение записывает объект
- **THEN** вызов за доли секунды завершается ошибкой недоступности, без
повторов
#### Scenario: S3 завис
- **WHEN** контейнер S3 заморожен (`docker pause`), и приложение
записывает объект
- **THEN** вызов завершается ошибкой недоступности не позже срока
вызова
#### Scenario: S3 вернулся
- **WHEN** S3 снова доступен, а приложение не перезапускалось
- **THEN** следующий вызов проходит
#### Scenario: Вызов после простоя
- **WHEN** приложение одновременно прочитало потоком несколько объектов
по несколько MiB, затем дольше срока вызова, но меньше срока жизни
простаивающего соединения не обращалось к S3, а S3 всё это время
доступен
- **THEN** следующие записи объектов проходят, ни одна не завершается
ошибкой недоступности
- **AND** S3 получает тело каждой записи целиком
#### Scenario: Объекта нет
- **WHEN** приложение читает ключ, которого в bucket нет
- **THEN** клиент сообщает, что объекта нет, а не недоступность S3
#### Scenario: Bucket нет
- **WHEN** bucket приложения удалён мимо bootstrap, и приложение
записывает, читает или удаляет объект либо запрашивает список объектов
- **THEN** каждый вызов завершается ошибкой недоступности, а не
сообщением «объекта нет» и не пустым списком, и в журнале есть запись
уровня `error`
#### Scenario: Учётные данные отклонены
- **WHEN** секрет API у приложения не совпадает с секретом на сервере
S3
- **THEN** вызов завершается ошибкой недоступности, а в журнале есть
запись уровня `error` без секрета
@@ -0,0 +1,109 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
объектов недоступно»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша»;
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
«Ключ после срока»;
- `api-conventions`: «Лимит одновременных загрузок»;
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не
видна», «Сбой записи метаданных», «Фиксация ready не удалась», «Обрыв
передачи тела», «Отказ раньше очереди», «Все места заняты», «Очередь
ожидания полна», «Ожидание места», «Место освобождается», «Медленный
клиент», «Медленная передача в срок», «Потерянный оригинал», «Загрузка
после простоя S3»;
- `storage-consistency`: все сценарии.
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL, Valkey и S3, применить
миграции и bootstrap S3;
- запустить четыре API:
- с настройками по умолчанию;
- «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом
из одного соединения;
- «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в
очереди, коротким сроком ожидания места и коротким сроком тела;
- «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой
дольше срока вызова в проверке длится полторы секунды, а не шесть.
Значения «узкого» API и API с коротким сроком S3 SHALL передаваться
проверкам, и проверки SHALL сверять с ними стенд;
- запустить уборщика с коротким grace и интервалом, сравнимыми со
временем теста, без плановой сверки, и передать их значения
проверкам. Grace при этом SHALL проходить проверку границы живой
загрузки (`service-configuration`, «Параметры уборщика»). Сверку
проверки запускают сами, и плановая сверка не меняет стенд у них за
спиной;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Hook стенда отказов SHALL уметь:
- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего
вложения в статусе «загружается» и `id` вложений с потерянным
оригиналом;
- сообщить, у каких вложений есть объект в bucket стенда, — по самим
объектам, а не по каталогам хранилища;
- внедрить отказ PostgreSQL:
- при записи метаданных загрузки с заданным `filename`;
- при фиксации её `ready`, и задержать такую фиксацию;
- при пометке потерянного оригинала такого вложения;
- убить и снова запустить обычный API стенда;
- внести расхождения хранилищ:
- записать объект в bucket стенда мимо API и удалить объект мимо API —
только под префиксом вложений базы стенда;
- удалить метаданные вложения, изменить в них размер и сдвинуть их
время в прошлое;
- выполнить разовую сверку — без изменений или с `--apply`, с заданным
пределом изменений — и вернуть её записи и код выхода;
- остановить и запустить уборщика стенда, а также запустить отдельного
уборщика с коротким интервалом плановой сверки на заданное время и
вернуть его журнал.
Других сведений о хранилищах проверки вложений не получают. Объекты без
метаданных проверка находит сравнением двух списков: вложений и
объектов. Ключи доступа S3 hook не получает и не печатает: объект мимо
API записывает процесс в контейнере стенда своими ключами.
Порты 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` удаляет их и начинает заново
@@ -0,0 +1,167 @@
# Tasks
Порядок: сначала тест и красный прогон на прежнем коде (группа 1), потом
правка (группа 2). Evidence для отчёта — с закоммиченного кода, commit
делает основная сессия (`bench.md`, «Измеренное состояние — commit»).
Рабочий стенд — `mtusi-lab4`, LB на `127.0.0.1:8090` (8080 занят чужим
проектом). Временные проекты compose, их volumes, сети и образы — убрать за
собой и сверить число volumes с исходным.
## 1. Тест до кода
- [ ] 1.1 `student-tests/api_client.py`: метод `Api` для скачивания
оригинала потоком с паузой между блоками. Он отдаёт статус, заголовки и
байты, идентификация — через `actor` (`student-tests.md`, «Как устроен
набор»). Проверка: `make lint`, метод использует тест 1.4.
- [ ] 1.2 `student-tests/run_failures.py`: четвёртый API
`<проект>-api-s3`:
- `S3_ENV = {"S3__TIMEOUT_SECONDS": "1"}`, тестам — `FAULT_S3_BASE_URL`
и `FAULT_S3_ENV`;
- контейнер — в списке для журналов при падении и для уборки, адрес — в
строке `ready:`;
- докстринг — «четыре контейнера API».
Проверка: `make failure_checks FAULT_ARGS='-k idle_s3'` печатает адрес
четвёртого API, после команды `docker ps -a` и `docker volume ls` с
меткой проекта отказов пусты.
- [ ] 1.3 `student-tests/conftest.py`: `FAULT_S3_BASE_URL` обязателен для
тестов `fault` (без него — выход с кодом 2, как у трёх адресов), фикстура
`s3_api` со сроком клиента 30 с. Проверка: `pytest -m fault` без стенда
останавливается до первого теста с кодом 2.
- [ ] 1.4 `student-tests/test_failures.py`: `test_upload_after_idle_s3`,
маркер `spec("attachments", "Загрузка после простоя S3")`, по design,
решение 3:
- `assert_s3_stand` сверяет `FAULT_S3_ENV` с ожидаемым;
- одна загрузка PNG из шума ~4 MiB;
- до 8 раундов: 10 одновременных скачиваний за барьером, у каждого
своё соединение, 2 мс на блок 64 KiB, байты равны загруженным;
простой `S3__TIMEOUT_SECONDS + 0,5` с; 12 загрузок `sample.png` по
одной — каждая 201;
- сообщение падения — номер раунда, номер загрузки и ответ;
- вероятность промаха (≈ 4e-12) — в докстринге.
Проверка: `make lint`.
- [ ] 1.5 Синхронизировать дельты `attachments`, `object-storage` и
`student-tests` в основные спеки (`openspec/specs/`): сверка покрытия
читает только их, и маркер нового сценария без этого — ссылка на
неизвестный сценарий. Проверка: `make student_test
BASE_URL=http://localhost:8090` — сверка покрытия (`test_coverage.py`)
зелёная, новый сценарий учтён как проверка отказов.
- [ ] 1.6 Красный прогон до правки: `make failure_checks FAULT_ARGS='-k
idle_s3'` три раза подряд на дереве с тестом и без правки 2.1. Каждый —
1 failed: 503 `unavailable` на загрузке после простоя, номер раунда — в
выводе. В журнале API стенда — `put_object` `ReadTimeoutError` за ~1 мс.
Выводы — в `evidence/tests/failure-checks.md`.
## 2. Правка клиента S3
- [ ] 2.1 `src/infra/s3/client.py`, `_create_client`: `read_timeout=None`
(design, решение 1). Рядом — комментарий:
- срок чтения aiohttp переживает ответ и портит соединение в пуле
(aiohttp 3.13–3.14.5);
- срок вызова и блока — `asyncio.timeout` в `_call` и `_read_chunk`;
- ссылка на design этого change.
В докстринг модуля — что срок только у приложения. Проверка: `make
lint`; зелёные тест 1.4 (2.2) и вариант образа `driver.py s3-idle`
(3.1).
- [ ] 2.2 Зелёный прогон: тот же `make failure_checks FAULT_ARGS='-k
idle_s3'` три раза — 1 passed каждый. Затем полный `make failure_checks`
— все проверки (49), признаков аварии PostgreSQL нет. Выводы — в
`evidence/tests/failure-checks.md`.
## 3. Драйвер и evidence механизма
- [ ] 3.1 `driver.py s3-idle` скилла `run-mtusi-messenger` (stdlib,
Python 3.9; design, решение 4):
- проба через `docker exec -i <реплика api> python -` в работающей
реплике стенда, uvloop, если есть;
- варианты «образ» и «эталон» (`read_timeout=[s3] timeout_seconds`);
- раунды 10 одновременных скачиваний 4 MiB с паузой 0,5 мс на блок,
простой `[s3] timeout_seconds + 0,5` с, 12 PUT; каждый записанный
объект читается обратно — размер и SHA-256;
- таблица по вариантам: взведено, испорчено, PUT прошло и упало,
класс и цепочка ошибки, мс. Нет закрытых полей aiohttp — «n/a»;
- объекты под `<база>/.s3-idle-probe/` удаляются в `finally`;
- код 0 — вариант образа без порчи, 1 — иначе, 2 — нет стенда.
Раздел в `SKILL.md`, строка в таблице команд AGENTS.md. Проверка:
- `driver.py --port 8090 s3-idle` на рабочем стенде до замены реплик
(реплики на прежнем коде): оба варианта портят соединения, код 1;
- после замены — повтор в 4.2;
- после команды объектов под `.s3-idle-probe/` нет: `weed shell fs.ls`
в контейнере S3.
- [ ] 3.2 `evidence/s3/idle-connection.md` (design, решение 4):
- механизм с местами в коде aiohttp 3.14.5, aiobotocore 3.9.2, botocore
1.43.106;
- вывод `driver.py s3-idle` до и после замены реплик;
- сводка захвата пакетов, таблица HTTP-раундов и сравнение с `f894040`
из design, Context;
- проверенные гипотезы.
Без ключей, подписей и значений заголовков. Проверка: `grep` по файлу
на `Authorization`, `Signature`, `AWS4-` и ключи `.env` пуст.
## 4. Регресс
- [ ] 4.1 `make lint`, `make check`, `make validate
PYTHON=.venv/bin/python` — без ошибок.
- [ ] 4.2 Новый образ на рабочем стенде: `make rolling_update`, затем
`docker compose up -d --no-deps cleaner`. Затем:
- `driver.py --port 8090 s3-idle`: у варианта образа 0 испорченных
соединений и 0 упавших PUT, эталон по-прежнему портит, код 0;
- `make student_test BASE_URL=http://localhost:8090` восемь раз подряд —
каждый без падений. В журналах реплик за эти прогоны нет «Object
storage is unavailable».
Итог — в `evidence/tests/student-test-lb.md` и
`evidence/s3/idle-connection.md`. Раздел «Повторные прогоны» дополняется
причиной и восемью прогонами после замены. Снимки для отчёта —
повторно с закоммиченного кода (шапка tasks).
- [ ] 4.3 `make test_isolated` — зелёный, тесты реплик пропущены с
причиной; `make test BASE_URL=http://localhost:8090` — smoke зелёный.
- [ ] 4.4 Одна копия тела: точечная проба PUT 10 MiB в образе API с
правкой. Это сценарий `put_memory_check.py` из `upload-memory`: тело в
`BytesIO`, `getvalue()`, `del`, `seek(0)`, PUT, пик `VmHWM` со сбросом.
Ожидание — ≤ 1,2 тела на трёх загрузках подряд, SHA-256 объектов
совпадает. Затем `make bench_uploads_quick` — разбор сводки без
ошибок, вердикты «с лимитом» прежние (метка `quick-*`, в git не идёт).
Числа — в `evidence/s3/idle-connection.md`.
- [ ] 4.5 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` —
зелёный: после рестарта S3 клиент без срока чтения aiohttp открывает
новые соединения, оригинал скачивается.
## 5. Документы
- [ ] 5.1 `.claude/rules/infra.md`, раздел S3 (design, решение 1):
- срок — только `asyncio.timeout` вызова и блока;
- `read_timeout` aiohttp выключен, почему, и запрет включать без новой
пробы;
- новое чтение из S3 — только через `_call` и `_read_chunk`;
- правило «повторов нет» прежнее.
Проверка: `grep -n read_timeout .claude/rules/infra.md` — только новая
формулировка.
- [ ] 5.2 `.claude/rules/student-tests.md`: четвёртый API стенда отказов,
`test_upload_after_idle_s3`, красный и зелёный прогоны, время прогона.
AGENTS.md: карта кода (`run_failures.py` — четыре API, `client.py` —
срок только приложения), таблица команд (`s3-idle`), описание `make
failure_checks`.
- [ ] 5.3 `REPORT.md`:
- клиент S3 — сроки и почему без срока чтения aiohttp;
- строка в «Эксперименты и отказы»: скачивания больших оригиналов,
затем простой S3 дольше срока — до правки 503 за 1 мс, после — 201;
- строка `make student_test` в таблице доказательств — без оговорки о
503, число проверок `make failure_checks`;
- в «Ограничениях» — дефект aiohttp 3.13–3.14.5 и как проект от него
закрыт.
- [ ] 5.4 `KNOWN_ISSUES.md`: запись «Изредка 503 на загрузке: PUT в S3
обрывается без тела» удаляется. `PLAN.md`:
- строка change в сводной таблице;
- раздел `### fix-upload-put-flake` дополняется решениями apply;
- ответ на вопрос 1, если он пришёл.
Проверка: `grep -n "Изредка 503" KNOWN_ISSUES.md` пуст.
- [ ] 5.5 `openspec validate fix-upload-put-flake --strict` — без ошибок.
Пересъёмка полной метки `make bench_uploads` в этот change не входит:
только по ответу пользователя на вопрос 1 `PLAN.md`.