docs: propose fix-upload-put-flake
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user