avandClaude Opus 4.8
4cc4de4269
Итог параллельной волны фиксов (worktree-изоляция, cherry-pick в master): - ingest-dedup-integrity (F1, F6) → спека ingest - retry-stall-basis (MAJOR-1, MAJOR-2) → спека state-reconciliation - linking-transition-robustness (MAJOR-4, MINOR-7) → спеки file-layout и state-reconciliation Дельты влиты в openspec/specs, changes перенесены в openspec/changes/archive/2026-07-08-*. Беклог не трогаю (по решению). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
105 lines
8.1 KiB
Markdown
105 lines
8.1 KiB
Markdown
# Design: retry/stall basis
|
||
|
||
## Контекст
|
||
|
||
Два таймаута зависания в `Worker.checkTimeouts` сегодня используют один базис —
|
||
возраст торрента `now − added_on`:
|
||
|
||
- `magnet_timeout`: `metaDL` дольше порога → `failed/magnet_timeout`.
|
||
- `stuck_after`: `stalledDL` дольше порога → `stuck/stalled`.
|
||
|
||
Для `magnet_timeout` возраст семантически верен (сколько торрент вообще висит
|
||
без метаданных). Для `stuck_after` возраст НЕВЕРЕН: нас интересует **простой**
|
||
(сколько данные не двигаются), а не общий возраст (MAJOR-2). Отдельно retry
|
||
живого торрента не сбрасывает базис, и задача мгновенно снова падает (MAJOR-1).
|
||
|
||
## Дизайн-развилка: откуда брать базис простоя/таймаута
|
||
|
||
Ключевое решение change — где взять базис для двух мер. Рассмотрены варианты:
|
||
|
||
- **(a) Новые колонки БД** `retried_at` и/или `stalled_since`. Базис возраста =
|
||
`max(added_on, retried_at)`; простой — от `stalled_since` (момент входа в
|
||
`stalledDL`, который мы сами детектируем и пишем/сбрасываем на каждом тике).
|
||
- **(b) Переиспользовать `last_activity` из снимка торрента** для измерения
|
||
простоя, без колонки на stall.
|
||
- **(c) Гибрид (ВЫБРАН):** колонка `retried_at` (только для сброса базиса при
|
||
ручном retry) + `last_activity` qBittorrent (для измерения простоя). Колонки
|
||
`stalled_since` НЕТ.
|
||
|
||
### Выбор: (c) `retried_at` (БД) + `last_activity` (qBit)
|
||
|
||
**Простой мерим по `last_activity`, а не по `stalled_since`-колонке.**
|
||
qBittorrent уже отдаёт `last_activity` (Unix-время последнего движения данных)
|
||
в том же ответе `/torrents/info` — это авторитетный источник «сколько простой»
|
||
прямо из движка. `stalled_since` дублировал бы это состояние, требовал бы
|
||
детектировать переход «вход в stalledDL», писать/сбрасывать колонку на КАЖДОМ
|
||
тике (торренты мерцают `stalledDL`↔`downloading`) и рисковал бы разъездом с
|
||
собственным взглядом qBittorrent. Простой = `now − last_activity`: торрент,
|
||
двигавший данные секунду назад, простаивает ~0 несмотря на возраст 5ч →
|
||
MAJOR-2 закрыт без схемы для stall. Это часть варианта (b).
|
||
|
||
**Сброс базиса при retry храним в `retried_at` (БД), а не в памяти.** Спека
|
||
требует, чтобы retry давал свежее окно и задача не падала снова. `last_activity`
|
||
этого не выражает: у по-настоящему простаивающего торрента она «часы назад», и
|
||
возврат в `downloading` тут же дал бы `stuck` на следующем тике. Нужна
|
||
персистентная метка «пользователь нажал retry в момент T», которая приподнимает
|
||
пол ОБОИХ базисов: `basis = max(добавление|last_activity, retried_at)`. Она
|
||
должна пережить интервал поллинга и рестарт процесса (retry, затем рестарт не
|
||
должен ронять задачу), поэтому — колонка, а не in-memory map. Это часть варианта
|
||
(a), но минимальная: одна nullable TEXT-колонка. Закрывает MAJOR-1.
|
||
|
||
### Почему не чистые (a) или (b)
|
||
|
||
- **Чистый (b) без колонки** — нельзя записать `last_activity` qBittorrent, так
|
||
что retry не смог бы сдвинуть базис → MAJOR-1 не решается.
|
||
- **Чистый (a) со `stalled_since`** — лишняя колонка + пер-тиковая
|
||
бухгалтерия входа/выхода из `stalledDL`, дублирующая `last_activity`. Отвергнут
|
||
на минимальности схемы и единственном источнике истины.
|
||
|
||
### Замечание об интеграции (точка человеческого вето)
|
||
|
||
Change читает НОВОЕ поле qBittorrent `last_activity`, но НЕ добавляет нового
|
||
вызова API или интеграционной поверхности — поле уже приходит в ответе
|
||
`/torrents/info`, парсим на одно поле больше. Это единственная «интеграция»
|
||
change, и она безопасна. Более глубокая интеграция для полного решения NIT-12
|
||
(см. ниже) СОЗНАТЕЛЬНО отложена как точка человеческого вето.
|
||
|
||
## Итоговая схема базисов
|
||
|
||
```
|
||
magnetAge = now − max( added_on | created_at(fallback), retried_at ) // magnet_timeout
|
||
stallIdle = now − max( last_activity | added_on|created_at(fallback), retried_at ) // stuck_after
|
||
```
|
||
|
||
- `addedBasis(d,t)` — `added_on`, иначе `created_at` (NIT-10), иначе базис
|
||
неизвестен (WARN, таймаут не срабатывает).
|
||
- `retriedFloor(d,basis)` — приподнимает базис до `retried_at`, если он позже.
|
||
- `retried_at` не чистится: как только данные двинулись, `last_activity`
|
||
естественно обгоняет `retried_at`, и пол перестаёт влиять.
|
||
|
||
## NIT-12: retry сломанного живого торрента
|
||
|
||
Живой торрент в `error`/`missingFiles` (класс `classErrored`) — перецепка к
|
||
нему бессмысленна: reconcile на ближайшем тике вернёт задачу в `failed`. Retry
|
||
теперь считает такой торрент «неживым для целей перецепки» и идёт по ветке
|
||
повторного `Add` (повторно отдаёт источник). Это честнее слепой перецепки:
|
||
retry перецепляется только к ЗДОРОВОМУ живому торренту.
|
||
|
||
**Остаточное ограничение (отложено, точка вето):** для устойчиво сломанного
|
||
торрента повторный `Add` того же infohash qBittorrent, как правило, дедуплицирует
|
||
— ошибка не очистится, и следующий тик всё равно вернёт задачу в `failed`. Полное
|
||
устранение (принудительный recheck / delete+re-add через qBittorrent) требует
|
||
НОВОЙ интеграции с клиентом и вынесено за рамки change на человеческое решение.
|
||
|
||
## Тесты
|
||
|
||
- `TestRetryResetsTimeoutBasis` — MAJOR-1: retry живого stalledDL-торрента с
|
||
давним `added_on` и давним `last_activity`, затем СЛЕДУЮЩИЙ тик Poll →
|
||
остаётся `downloading` (без сброса базиса ушёл бы в `stuck`). Именно эту
|
||
регрессию прячет `TestRetryReattachesNoReadd`.
|
||
- `TestStallMeasuredFromLastActivity` — MAJOR-2: `stalledDL` с давним `added_on`,
|
||
но свежим `last_activity` → `downloading`; контроль — давняя `last_activity` →
|
||
`stuck`.
|
||
- `TestSetRetriedAtOverwrites` — store: `retried_at` перезаписывается (в отличие
|
||
от однократного `source_added_at`).
|