Приём: пропажа источника у активной загрузки → failed(source_gone) (MAJOR-3)
Раздача активной (downloading) загрузки, исчезнувшая из qBittorrent (удалил пользователь/другой клиент), делала задачу вечным зомби: поллинг промахивался по torrentFor, писал Warn и continue каждый тик — состояние не менялось, уведомления и телеметрии не было, checkTimeouts без торрента не срабатывал. Пропажей источника у downloading не владел никто (сверка рассинхрона покрывает только done/target_missing/orphaned, восстановление — failed/stuck). Активный цикл Poll теперь применяет тот же дебаунс пропажи источника, что и сверка рассинхрона (source_miss_count / source_missing_threshold): после порога подряд идущих промахов задача уходит downloading → failed с distinct error_code source_gone и уведомлением. До порога транзиентная недоступность qBit (рестарт демона) задачу не роняет. source_gone восстановлению сверкой не подлежит (удаление намеренно), но штатно retriable — Retry заново отдаёт сохранённый источник; Retry сбрасывает source_miss_count, чтобы вернувшаяся задача получила полное грейс-окно, а не упала снова на ближайшем тике. Ребро downloading → failed уже было в графе, миграций/полей БД нет. Спека download-tracking дополнена требованием, диаграмма workflow.md — ребром. Change downloading-source-gone заархивирован. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-08
|
||||
@@ -0,0 +1,135 @@
|
||||
# Design — Пропажа источника у активной загрузки
|
||||
|
||||
## Контекст
|
||||
|
||||
`Poll` под `w.mu` листает `downloading`-задачи и для каждой ищет торрент в
|
||||
`byHash`. Промах сейчас — только `Warn` + `continue` (worker.go:503-508). Механизм
|
||||
дебаунса пропажи источника уже есть в `state-reconciliation`: поле
|
||||
`download.source_miss_count`, метод `debounceSource(ctx, d, sourceSeen) bool` и
|
||||
порог `[worker].source_missing_threshold` (дефолт 3). Он применяется только в
|
||||
`reconcileOneDesync`. Задача — переиспользовать его в активном цикле.
|
||||
|
||||
## Решение
|
||||
|
||||
### Целевое состояние: `failed`/`source_gone`, а не `deleted`
|
||||
|
||||
Развилка из беклога: «downloading → `deleted` ИЛИ `failed` с distinct error_code
|
||||
для re-Add». Выбран **`failed`/`source_gone`**:
|
||||
|
||||
- **Восстановимость.** Источник у нас сохранён (magnet `source_ref` или байты
|
||||
`.torrent`). `Retry` заново отдаёт его в qBittorrent — задача продолжится.
|
||||
`deleted` терминален навсегда и не оставляет пользователю выхода, хотя пропажа
|
||||
могла быть случайной.
|
||||
- **Минимальная дельта графа.** Ребро `downloading → failed` уже объявлено
|
||||
(`allowedTransitions`), нового ребра не нужно. `downloading → deleted` ребра нет
|
||||
— пришлось бы вводить.
|
||||
- **Переиспользование инфраструктуры.** `StateFailed` уже шлёт `EventFailed`
|
||||
(с дебаунсом уведомлений) и уже retriable — не нужен ни новый notify-повод, ни
|
||||
новая команда.
|
||||
- **Distinct `error_code`.** `source_gone` отличается от `qbit_error`
|
||||
(реальная ошибка qBit), `magnet_timeout`/`stalled` (наша нетерпеливость) — по
|
||||
нему UI/лог различает причину, и он **осознанно не в наборе** `reconcileRecovery`
|
||||
(`ListRecoverable(magnet_timeout, stalled)`): намеренно удалённый источник не
|
||||
должен молча воскресать, у пользователя есть явный `Retry`.
|
||||
|
||||
`deriveState(false, false) = deleted` (матрица «источник × цель») здесь НЕ
|
||||
применяется: у активной `downloading`-задачи цели ещё нет, и это не путь сверки
|
||||
рассинхрона, а отдельное правило прямого пути. Матрица по-прежнему не трогает
|
||||
активные состояния.
|
||||
|
||||
### Переиспользование дебаунса в активном цикле
|
||||
|
||||
`debounceSource(ctx, d, sourceSeen)`:
|
||||
- `sourceSeen=true` → сбрасывает счётчик в 0, возвращает `true`;
|
||||
- `sourceSeen=false` → инкремент, возвращает `miss < threshold`.
|
||||
|
||||
Активный цикл `Poll` перестраивается так:
|
||||
|
||||
```go
|
||||
t, ok := torrentFor(d, byHash)
|
||||
if present := w.debounceSource(ctx, d, ok); !present {
|
||||
// порог промахов исчерпан — источник действительно пропал
|
||||
lctx := w.scoped(ctx, capIngest, d.ID, d.PrimaryInfohash())
|
||||
w.transition(lctx, d, store.StateFailed, errCodeSourceGone,
|
||||
"источник удалён из qBittorrent")
|
||||
continue
|
||||
}
|
||||
if !ok {
|
||||
// до порога: транзиентный промах (рестарт qBit) — ждём следующий тик
|
||||
continue
|
||||
}
|
||||
w.captureInfohashes(ctx, d, t)
|
||||
w.captureSourceAddedAt(ctx, d, t)
|
||||
w.reconcile(ctx, d, t)
|
||||
```
|
||||
|
||||
`debounceSource` вызывается в ЛЮБОМ случае (и при `ok`, и при промахе), поэтому
|
||||
появление раздачи сбрасывает счётчик, накопленный ранее.
|
||||
|
||||
### Сброс `source_miss_count` при `Retry` (иначе нет грейс-окна)
|
||||
|
||||
`source_gone` — единственный путь, оставляющий у **retriable** задачи ненулевой
|
||||
`source_miss_count` (у `magnet_timeout`/`stalled` источник на падающем тике
|
||||
присутствовал, значит счётчик уже 0). Без сброса `Retry` вернул бы задачу в
|
||||
`downloading` с `source_miss_count == threshold`: на первом же тике, если
|
||||
переотданная раздача ещё не видна в выдаче qBittorrent (Add без ошибки, но
|
||||
регистрация с задержкой), `debounceSource` даёт `miss = threshold+1` → мгновенный
|
||||
повторный `source_gone`, минуя обещанное спекой грейс-окно.
|
||||
|
||||
Поэтому `Retry` SHALL сбрасывать `source_miss_count` в 0 — рядом с существующим
|
||||
сбросом `retried_at` (та же интенция «свежее окно», MAJOR-1), best-effort. Это
|
||||
покрывает общий случай: любая retriable-задача входит в `downloading` с чистым
|
||||
счётчиком. Путь авто-восстановления (`reconcileRecovery`) сброса не требует —
|
||||
туда `source_gone` не попадает, а у `magnet_timeout`/`stalled` счётчик уже 0.
|
||||
|
||||
### Почему нет двойного учёта `source_miss_count`
|
||||
|
||||
Задача в один момент времени находится ровно в одном состоянии: либо в активном
|
||||
цикле (`downloading`), либо в `reconcileDesync` (`done`/`target_missing`/
|
||||
`orphaned`) — не в обоих за тик. Поле `source_miss_count` используется с единой
|
||||
семантикой «сброс при наличии источника», поэтому пересечения нет. При переходе
|
||||
`downloading → completed` счётчик уже 0 (источник виден на том же тике).
|
||||
|
||||
### catched-исключение сохраняется
|
||||
|
||||
`catched`-задачи в активный цикл не попадают (там нет раздачи по дизайну) —
|
||||
требование «catched не считается пропажей раздачи» не затрагивается: цикл листает
|
||||
только `StateDownloading`.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
- **`downloading → deleted`** — отклонено: терминально без выхода, требует нового
|
||||
ребра, теряет ещё-скачиваемую задачу при, возможно, случайной пропаже.
|
||||
- **Авто-восстановление `source_gone` при возврате раздачи** (добавить в
|
||||
`reconcileRecovery`) — отклонено для v1: намеренное удаление не должно тихо
|
||||
оживать; есть явный `Retry`. Отложено (можно добавить позже отдельным change,
|
||||
если появится боль).
|
||||
- **Отдельный notify-повод `EventSourceGone`** — избыточно: `EventFailed`
|
||||
семантически покрывает «задача упала», текст уведомления берётся по состоянию.
|
||||
|
||||
## Принятые ограничения (вне scope)
|
||||
|
||||
- **Дебаунс уведомлений может проглотить пинг.** `shouldNotifyFail` дебаунсит
|
||||
`EventFailed` по `download_id` на 1 ч. Узкая последовательность (задача уже
|
||||
падала `stalled`/`stuck` с пингом < 1 ч назад → `Retry` → источник удалён →
|
||||
`source_gone` в то же окно) не пришлёт повторный пинг. Приемлемо: смена
|
||||
состояния и телеметрия всё равно фиксируются (главная боль зомби — «никто не
|
||||
двигает» — закрыта); отдельный пинг именно про source_gone не критичен.
|
||||
- **Задача `downloading` с пустым `Infohashes`** остаётся вне правила: гард
|
||||
`len(d.Infohashes)==0 { continue }` стоит до `torrentFor` (как и в
|
||||
`reconcileOneDesync`). В Ф1 не случается (magnet всегда с infohash); отдельный
|
||||
класс зомби, этим change не адресуется.
|
||||
- **Пустая выдача qBittorrent при живом демоне** (HTTP 200 сразу после рестарта,
|
||||
resume-data ещё не загружены) нарастит промахи всем активным задачам. Экспозиция
|
||||
предсуществующая и общая с `reconcileDesync` (тот массово пометил бы
|
||||
`orphaned`/`deleted`); change лишь распространяет её на активные загрузки.
|
||||
Дебаунс (`source_missing_threshold`) — уже имеющаяся защита; принимаем.
|
||||
|
||||
## Тесты
|
||||
|
||||
- Промах меньше порога → задача остаётся `downloading` (дебаунс).
|
||||
- Промах ≥ порога → `downloading → failed`/`source_gone` + `EventFailed`.
|
||||
- Возврат раздачи до порога → счётчик сброшен, задача жива, ушла по обычному
|
||||
reconcile.
|
||||
- `source_gone` не воскрешается `reconcileRecovery` (источник вернулся — задача
|
||||
остаётся `failed` до ручного `Retry`).
|
||||
@@ -0,0 +1,47 @@
|
||||
# Пропажа источника у активной загрузки (MAJOR-3)
|
||||
|
||||
## Why
|
||||
|
||||
Если раздача исчезает из qBittorrent (пользователь или другой клиент удалил её),
|
||||
пока задача в `downloading`, задача становится **вечным зомби**. Поллинг активных
|
||||
загрузок промахивается по `torrentFor`, пишет `Warn "active download not found in
|
||||
qbittorrent"` и делает `continue` — и так каждый тик, бесконечно. Состояние не
|
||||
меняется, уведомления нет, телеметрии нет, `checkTimeouts` требует торрент (значит
|
||||
таймауты-предохранители не срабатывают). Единственный выход — ручной Cancel/Defer.
|
||||
|
||||
Дыра: сверка рассинхрона (`state-reconciliation`) покрывает пропажу источника
|
||||
только для уже разложенных состояний (`done`/`target_missing`/`orphaned`), а
|
||||
восстановление (`reconcileRecovery`) — только `failed`/`stuck`. Для активного
|
||||
`downloading` пропажей источника не владеет НИКТО. Сравни: та же пропажа в
|
||||
`completed`/`recognizing`/`review` деградирует штатно (там источник уже не нужен
|
||||
или его отсутствие ведёт через матрицу).
|
||||
|
||||
## What Changes
|
||||
|
||||
- Поллинг активных загрузок SHALL применять **дебаунс пропажи источника** (тот же
|
||||
`SourceMissCount` / `[worker].source_missing_threshold`, что и сверка
|
||||
рассинхрона): промах `torrentFor` наращивает счётчик, любое появление раздачи
|
||||
его сбрасывает.
|
||||
- После порога подряд идущих промахов задача SHALL переходить `downloading →
|
||||
failed` с новым отдельным `error_code` `source_gone` и уведомлять автора
|
||||
(`EventFailed`).
|
||||
- `source_gone` **восстановлению сверкой не подлежит** (не входит в набор
|
||||
`reconcileRecovery`): удаление источника из qBittorrent — намеренное действие,
|
||||
молча воскрешать задачу нельзя. Задача остаётся штатно **retriable**: `Retry`
|
||||
заново отдаёт источник (у нас сохранены magnet/`.torrent`-байты).
|
||||
|
||||
Ребро графа `downloading → failed` уже объявлено — нового ребра не требуется.
|
||||
Меняется только набор `error_code` и поведение поллинга активных загрузок.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- `download-tracking` — ADDED: «Пропажа источника у активной загрузки».
|
||||
|
||||
## Impact
|
||||
|
||||
- Код: `internal/worker/worker.go` (поллинг активных загрузок, новый
|
||||
`errCodeSourceGone`), тесты воркера.
|
||||
- Спека: `download-tracking` (новое требование). Диаграмма `docs/specs/workflow.md`
|
||||
(миррор FSM) — добавить ребро `downloading → failed (source_gone)`.
|
||||
- Миграции БД нет: `source_miss_count` уже существует, новых полей не вводим.
|
||||
- Конфиг без изменений: переиспользуем `source_missing_threshold`.
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
# download-tracking Specification
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Пропажа источника у активной загрузки
|
||||
|
||||
Поллинг активных загрузок (`downloading`) SHALL обнаруживать пропажу источника:
|
||||
если раздача, совпадающая с любым из известных хешей загрузки, отсутствует в
|
||||
выдаче qBittorrent, система SHALL применять **тот же дебаунс пропажи источника**,
|
||||
что и сверка рассинхрона (счётчик `source_miss_count`, порог
|
||||
`[worker].source_missing_threshold`; см. `state-reconciliation` «Дебаунс пропажи
|
||||
источника»). Любое обнаружение раздачи SHALL сбрасывать счётчик.
|
||||
|
||||
После `N` подряд идущих тиков без раздачи (`N =
|
||||
[worker].source_missing_threshold`) система SHALL переводить загрузку
|
||||
`downloading → failed` с `error_code` `source_gone` и уведомлять автора. До
|
||||
достижения порога загрузка SHALL оставаться в `downloading` (транзиентная
|
||||
недоступность qBittorrent, например рестарт демона, не должна ронять задачу).
|
||||
|
||||
`source_gone` система SHALL трактовать как отдельную причину, отличную от
|
||||
`qbit_error` (реальная ошибка qBittorrent) и от `magnet_timeout`/`stalled` (наша
|
||||
нетерпеливость). Восстановлению сверкой (`reconcileRecovery`) `source_gone`
|
||||
подлежать SHALL NOT — удаление источника из qBittorrent намеренно, молча
|
||||
воскрешать задачу нельзя. Задача SHALL оставаться штатно восстановимой вручную
|
||||
(`Retry` заново отдаёт сохранённый источник в qBittorrent).
|
||||
|
||||
Состояние `catched` этим правилом затрагиваться SHALL NOT: у пойманной загрузки
|
||||
раздачи в qBittorrent ещё нет по дизайну (см. «catched не считается пропажей
|
||||
раздачи»), а цикл активных загрузок листает только `downloading`.
|
||||
|
||||
#### Scenario: Источник пропал у активной загрузки дольше порога
|
||||
|
||||
- **GIVEN** загрузка в `downloading`, чья раздача удалена из qBittorrent
|
||||
- **WHEN** раздача отсутствует `source_missing_threshold` подряд идущих тиков
|
||||
- **THEN** загрузка переходит в `failed` с `error_code` `source_gone`
|
||||
- **AND** автор загрузки уведомляется
|
||||
|
||||
#### Scenario: Кратковременная пропажа источника не роняет задачу
|
||||
|
||||
- **GIVEN** загрузка в `downloading`
|
||||
- **WHEN** раздача отсутствует в qBittorrent меньше `source_missing_threshold`
|
||||
тиков подряд
|
||||
- **THEN** загрузка остаётся в `downloading`
|
||||
|
||||
#### Scenario: Возврат раздачи сбрасывает счётчик
|
||||
|
||||
- **GIVEN** загрузка в `downloading` с накопленными промахами источника (меньше
|
||||
порога)
|
||||
- **WHEN** раздача снова обнаружена в qBittorrent
|
||||
- **THEN** счётчик промахов сбрасывается в ноль и загрузка ведётся обычной
|
||||
сверкой состояния
|
||||
|
||||
#### Scenario: source_gone не воскрешается сверкой
|
||||
|
||||
- **GIVEN** загрузка в `failed` с `error_code` `source_gone`
|
||||
- **WHEN** её раздача снова появляется в qBittorrent и продвигается
|
||||
- **THEN** сверка восстановления её не трогает — задача остаётся в `failed` до
|
||||
ручного `Retry`
|
||||
@@ -0,0 +1,38 @@
|
||||
# Tasks — Пропажа источника у активной загрузки
|
||||
|
||||
## 1. Код воркера
|
||||
|
||||
- [x] 1.1 Ввести `errCodeSourceGone = "source_gone"` в блок кодов ошибок
|
||||
(`internal/worker/worker.go`) с комментарием: distinct-код, восстановлению
|
||||
сверкой не подлежит, retriable вручную.
|
||||
- [x] 1.2 Перестроить активный цикл в `Poll`: при промахе `torrentFor` прогонять
|
||||
`debounceSource`; при исчерпании порога — `transition downloading → failed`
|
||||
(`source_gone`); до порога — `continue`; при наличии источника — сброс счётчика
|
||||
и обычная сверка (`captureInfohashes`/`captureSourceAddedAt`/`reconcile`).
|
||||
- [x] 1.3 Убедиться, что `debounceSource` вызывается и при наличии источника
|
||||
(сброс накопленных промахов).
|
||||
- [x] 1.4 `Retry` сбрасывает `source_miss_count` в 0 (рядом с `SetRetriedAt`),
|
||||
чтобы retried `source_gone`-задача получила полное грейс-окно, а не падала
|
||||
сразу (см. design «Сброс source_miss_count при Retry»).
|
||||
|
||||
## 2. Тесты
|
||||
|
||||
- [x] 2.1 Промах < порога → задача остаётся `downloading`.
|
||||
- [x] 2.2 Промах ≥ порога → `downloading → failed`/`source_gone` + `EventFailed`.
|
||||
- [x] 2.3 Возврат раздачи до порога → счётчик сброшен, задача ведётся обычной
|
||||
сверкой.
|
||||
- [x] 2.4 `source_gone` не воскрешается `reconcileRecovery` (источник вернулся —
|
||||
задача остаётся `failed`).
|
||||
- [x] 2.5 `Retry` задачи `source_gone` сбрасывает `source_miss_count`: после
|
||||
retry с ещё-не-видимой раздачей задача остаётся `downloading` полный порог
|
||||
тиков (грейс-окно не съедено).
|
||||
|
||||
## 3. Документация
|
||||
|
||||
- [x] 3.1 `docs/specs/workflow.md`: добавить ребро `downloading → failed`
|
||||
(`source_gone`, пропажа источника) в диаграмму и список переходов.
|
||||
|
||||
## 4. Верификация
|
||||
|
||||
- [x] 4.1 `task test` / `task lint` зелёные.
|
||||
- [x] 4.2 `openspec validate downloading-source-gone --strict`.
|
||||
@@ -242,3 +242,58 @@ SHALL проходить только revive-путём (`ActivateIfNoOtherActiv
|
||||
- **AND** тот же переход через `ActivateIfNoOtherActive` (при свободном infohash)
|
||||
проходит
|
||||
|
||||
### Requirement: Пропажа источника у активной загрузки
|
||||
|
||||
Поллинг активных загрузок (`downloading`) SHALL обнаруживать пропажу источника:
|
||||
если раздача, совпадающая с любым из известных хешей загрузки, отсутствует в
|
||||
выдаче qBittorrent, система SHALL применять **тот же дебаунс пропажи источника**,
|
||||
что и сверка рассинхрона (счётчик `source_miss_count`, порог
|
||||
`[worker].source_missing_threshold`; см. `state-reconciliation` «Дебаунс пропажи
|
||||
источника»). Любое обнаружение раздачи SHALL сбрасывать счётчик.
|
||||
|
||||
После `N` подряд идущих тиков без раздачи (`N =
|
||||
[worker].source_missing_threshold`) система SHALL переводить загрузку
|
||||
`downloading → failed` с `error_code` `source_gone` и уведомлять автора. До
|
||||
достижения порога загрузка SHALL оставаться в `downloading` (транзиентная
|
||||
недоступность qBittorrent, например рестарт демона, не должна ронять задачу).
|
||||
|
||||
`source_gone` система SHALL трактовать как отдельную причину, отличную от
|
||||
`qbit_error` (реальная ошибка qBittorrent) и от `magnet_timeout`/`stalled` (наша
|
||||
нетерпеливость). Восстановлению сверкой (`reconcileRecovery`) `source_gone`
|
||||
подлежать SHALL NOT — удаление источника из qBittorrent намеренно, молча
|
||||
воскрешать задачу нельзя. Задача SHALL оставаться штатно восстановимой вручную
|
||||
(`Retry` заново отдаёт сохранённый источник в qBittorrent).
|
||||
|
||||
Состояние `catched` этим правилом затрагиваться SHALL NOT: у пойманной загрузки
|
||||
раздачи в qBittorrent ещё нет по дизайну (см. «catched не считается пропажей
|
||||
раздачи»), а цикл активных загрузок листает только `downloading`.
|
||||
|
||||
#### Scenario: Источник пропал у активной загрузки дольше порога
|
||||
|
||||
- **GIVEN** загрузка в `downloading`, чья раздача удалена из qBittorrent
|
||||
- **WHEN** раздача отсутствует `source_missing_threshold` подряд идущих тиков
|
||||
- **THEN** загрузка переходит в `failed` с `error_code` `source_gone`
|
||||
- **AND** автор загрузки уведомляется
|
||||
|
||||
#### Scenario: Кратковременная пропажа источника не роняет задачу
|
||||
|
||||
- **GIVEN** загрузка в `downloading`
|
||||
- **WHEN** раздача отсутствует в qBittorrent меньше `source_missing_threshold`
|
||||
тиков подряд
|
||||
- **THEN** загрузка остаётся в `downloading`
|
||||
|
||||
#### Scenario: Возврат раздачи сбрасывает счётчик
|
||||
|
||||
- **GIVEN** загрузка в `downloading` с накопленными промахами источника (меньше
|
||||
порога)
|
||||
- **WHEN** раздача снова обнаружена в qBittorrent
|
||||
- **THEN** счётчик промахов сбрасывается в ноль и загрузка ведётся обычной
|
||||
сверкой состояния
|
||||
|
||||
#### Scenario: source_gone не воскрешается сверкой
|
||||
|
||||
- **GIVEN** загрузка в `failed` с `error_code` `source_gone`
|
||||
- **WHEN** её раздача снова появляется в qBittorrent и продвигается
|
||||
- **THEN** сверка восстановления её не трогает — задача остаётся в `failed` до
|
||||
ручного `Retry`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user