jellybit/openspec/changes/archive/2026-06-30-download-failure-recovery/specs/state-reconciliation/spec.md at f8fb4fabb37e2661baefa52694f8e36d73b852f2

av/jellybit

Fork 0

Files

T

avandClaude Opus 4.8 70d8758646

Восстановление зависших загрузок и уведомления о падении (state-reconciliation)

Долгий metaDL больше не убивается агрессивным таймаутом: дефолт
magnet_timeout 30m → 24h (страховочный предохранитель), базис отсчёта —
added_on из qBittorrent, а не created_at (переживает retry/усыновление).

Авто-восстановление: фоновая сверка возвращает в поток задачи, упавшие по
нашей нетерпеливости (magnet_timeout/stalled), когда источник ожил и
продвинулся за условие падения (downloading/completed по статусу торрента);
qbit_error не воскрешается. Конфликт idempotency (infohash занят другой
активной задачей) — оставляем в failed.

Уведомления: любой переход в failed/stuck пингует автора (включая приёмный
qbit_add через ingest), с дебаунсом против спама при флаппинге stalled.
Ручной retry добавлен в веб-UI и Telegram; Retry перецепляется к живому
торренту вместо слепого Add.

Дельта state-reconciliation влита в живые спеки; обновлён workflow.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-30 14:51:57 +03:00

9.9 KiB

Raw Blame History

MODIFIED Requirements

Requirement: Периодическая сверка состояния с реальностью

worker SHALL периодически (на тике поллинга) сверять задачи, для которых ожидаются разложенные файлы, с фактом на файловой системе и в qBittorrent, и выводить состояние задачи из двух независимых признаков: присутствия источника (раздача с download.infohash в выдаче qBittorrent) и присутствия цели (см. требование о владении целевым путём: существуют все ссылки последнего батча со статусом раскладки, всё ещё принадлежащие этой загрузке).

Сверке по матрице «источник × цель» SHALL подвергаться состояния done, target_missing, orphaned. Состояние deleted сверка трогать SHALL NOT — оно терминально. Активные (downloading/recognizing/review/deferred/ linking) и пользовательски-терминальные (reverted/cancelled) состояния сверка по матрице трогать SHALL NOT.

Восстановимые failed/stuck (с error_code magnet_timeout или stalled — задержки, вызванные нашей нетерпеливостью, а не реальной ошибкой) сверка SHALL рассматривать отдельно — на предмет оживления источника (см. требование о восстановлении зависшей загрузки), не по матрице «источник × цель». Прочие failed (например qbit_error) сверка трогать SHALL NOT.

Состояние SHALL переписываться только при его изменении (без записи и логов, когда выведенное состояние совпадает с текущим).

Scenario: Источник и цель на месте — состояние не меняется

WHEN для задачи в done раздача присутствует в qBittorrent и все её разложенные хардлинки существуют
THEN задача остаётся в done
AND запись состояния и лог перехода не выполняются

Scenario: Частичная пропажа цели считается отсутствием

WHEN часть разложенных хардлинков задачи удалена, а источник на месте
THEN цель считается отсутствующей и задача переходит в target_missing

Scenario: Задача в deleted сверкой не переоценивается

WHEN задача находится в deleted
THEN сверка её не рассматривает и состояние не меняет, даже если по её бывшему пути появился файл другой загрузки

Scenario: Провал по ошибке qBittorrent восстановлению не подлежит

WHEN задача в failed с error_code qbit_error
THEN сверка её не рассматривает и состояние не меняет

ADDED Requirements

Requirement: Восстановление зависшей загрузки при оживлении источника

Система SHALL возвращать в активный поток задачу, упавшую из-за нашей нетерпеливости (failed/magnet_timeout или stuck/stalled), если её источник в qBittorrent жив и продвинулся: переход выводится из текущего состояния торрента так же, как при штатной сверке загрузки (uploading/stalledUP/… → completed; downloading/metaDL/… → downloading). Восстановление SHALL опираться на фактическое состояние торрента в qBittorrent, а не на время с момента создания записи.

При возврате в любое нетерминальное состояние (downloading или completed) система SHALL восстанавливать идемпотентность задачи (idempotency_key), чтобы повторный приём того же infohash снова дедуплицировался на эту задачу. Если за время простоя в failed/stuck тем же infohash уже завладела другая активная задача (ключ снимается при падении и мог быть перехвачен новым приёмом), система SHALL NOT воскрешать упавшую задачу и SHALL оставить её в failed/stuck, сохраняя инвариант «не более одной активной задачи на infohash».

magnet_timeout/stalled SHALL быть редким страховочным исходом, а не рабочим механизмом: пока торрент в metaDL/forcedMetaDL или иным образом прогрессирует в пределах страховочного таймаута, задача в failed/stuck из-за него оказаться SHALL NOT (см. требование о терпеливости к долгим метаданным в docs/specs/workflow.md).

Scenario: Метаданные пришли после magnet_timeout

GIVEN задача в failed с error_code magnet_timeout, а её торрент в qBittorrent уже получил метаданные и качается (downloading)
WHEN срабатывает фоновая сверка
THEN задача возвращается в downloading
AND её idempotency_key восстанавливается

Scenario: Торрент уже завершился, пока задача была в failed

GIVEN задача в failed с error_code magnet_timeout, а её торрент в qBittorrent уже готов к раскладке (uploading/stalledUP)
WHEN срабатывает фоновая сверка
THEN задача переходит в completed и продолжает обычный поток (распознавание/раскладка)

Scenario: Источник так и не ожил — состояние не меняется

GIVEN задача в failed с error_code magnet_timeout, а её торрент всё ещё висит в metaDL без метаданных (или отсутствует в qBittorrent)
WHEN срабатывает фоновая сверка
THEN задача остаётся в failed

Scenario: infohash уже занят другой активной задачей

GIVEN задача #1 в failed/magnet_timeout, а тем же infohash уже владеет другая активная задача #2 (приём повторили, пока #1 лежала упавшей)
WHEN источник ожил (торрент получил метаданные или готов) и сверка пытается воскресить #1
THEN #1 остаётся в failed (восстановление не выполняется)
AND активной по этому infohash остаётся #2

Requirement: Ручной повтор зависшей/упавшей загрузки из транспортов

Система SHALL предоставлять пользователю команду повторной попытки (retry) для задач в failed/stuck из веб-UI и Telegram (не только через REST API). Retry SHALL переводить задачу обратно в downloading, не вызывая её немедленного повторного падения по таймауту: базис отсчёта таймаута SHALL сбрасываться (отсчёт ведётся от факта в qBittorrent, а не от старого created_at).

Если источник задачи уже жив в qBittorrent, retry SHALL перецепляться к существующему торренту, а не добавлять источник повторно вслепую; повторный Add выполняется, только когда раздачи в qBittorrent нет.

Scenario: Retry упавшей magnet-загрузки из веб-UI

GIVEN задача в failed, её торрент жив в qBittorrent
WHEN пользователь нажимает retry в веб-UI
THEN задача возвращается в downloading без повторного Add
AND не падает снова на ближайшем тике сверки по таймауту

Scenario: Retry доступен в Telegram

WHEN для задачи в failed/stuck пользователь вызывает retry в Telegram-боте
THEN задача возвращается в downloading

Scenario: Retry без живого источника добавляет торрент заново

GIVEN задача в failed, раздачи в qBittorrent нет
WHEN пользователь инициирует retry
THEN источник (magnet) добавляется в qBittorrent заново
AND задача переходит в downloading

9.9 KiB Raw Blame History Unescape Escape