From 7d4b2cb37ef583ca320806b994469d21d5a42154 Mon Sep 17 00:00:00 2001 From: roman Date: Thu, 22 Oct 2026 22:52:59 +0300 Subject: [PATCH] docs: propose fix-upload-put-flake Co-Authored-By: Claude Opus 5.5 --- PLAN.md | 88 ++++ .../fix-upload-put-flake/.openspec.yaml | 2 + .../changes/fix-upload-put-flake/design.md | 390 ++++++++++++++++++ .../changes/fix-upload-put-flake/proposal.md | 97 +++++ .../specs/attachments/spec.md | 46 +++ .../specs/object-storage/spec.md | 93 +++++ .../specs/student-tests/spec.md | 109 +++++ .../changes/fix-upload-put-flake/tasks.md | 167 ++++++++ 8 files changed, 992 insertions(+) create mode 100644 openspec/changes/fix-upload-put-flake/.openspec.yaml create mode 100644 openspec/changes/fix-upload-put-flake/design.md create mode 100644 openspec/changes/fix-upload-put-flake/proposal.md create mode 100644 openspec/changes/fix-upload-put-flake/specs/attachments/spec.md create mode 100644 openspec/changes/fix-upload-put-flake/specs/object-storage/spec.md create mode 100644 openspec/changes/fix-upload-put-flake/specs/student-tests/spec.md create mode 100644 openspec/changes/fix-upload-put-flake/tasks.md diff --git a/PLAN.md b/PLAN.md index 297f8afc..f6eeb0f8 100644 --- a/PLAN.md +++ b/PLAN.md @@ -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` остаётся. diff --git a/openspec/changes/fix-upload-put-flake/.openspec.yaml b/openspec/changes/fix-upload-put-flake/.openspec.yaml new file mode 100644 index 00000000..7cc41bb5 --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-22 diff --git a/openspec/changes/fix-upload-put-flake/design.md b/openspec/changes/fix-upload-put-flake/design.md new file mode 100644 index 00000000..0002c1fb --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/design.md @@ -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), план +и задачи от ответа не зависят. diff --git a/openspec/changes/fix-upload-put-flake/proposal.md b/openspec/changes/fix-upload-put-flake/proposal.md new file mode 100644 index 00000000..5efcf8de --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/proposal.md @@ -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). diff --git a/openspec/changes/fix-upload-put-flake/specs/attachments/spec.md b/openspec/changes/fix-upload-put-flake/specs/attachments/spec.md new file mode 100644 index 00000000..9a0b2493 --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/specs/attachments/spec.md @@ -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** скачанные байты совпадают с загруженными diff --git a/openspec/changes/fix-upload-put-flake/specs/object-storage/spec.md b/openspec/changes/fix-upload-put-flake/specs/object-storage/spec.md new file mode 100644 index 00000000..f3720f27 --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/specs/object-storage/spec.md @@ -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` без секрета diff --git a/openspec/changes/fix-upload-put-flake/specs/student-tests/spec.md b/openspec/changes/fix-upload-put-flake/specs/student-tests/spec.md new file mode 100644 index 00000000..8c6cc724 --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/specs/student-tests/spec.md @@ -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` удаляет их и начинает заново diff --git a/openspec/changes/fix-upload-put-flake/tasks.md b/openspec/changes/fix-upload-put-flake/tasks.md new file mode 100644 index 00000000..9d08ee6f --- /dev/null +++ b/openspec/changes/fix-upload-put-flake/tasks.md @@ -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`.