jellybit/openspec/changes/archive/2026-06-30-download-failure-recovery/design.md

Context

Машина состояний загрузок живёт в internal/worker/worker.go (Poll/reconcile/checkTimeouts/transition/Retry), список состояний и терминальность — в internal/store/download.go. Граф переходов описан в docs/specs/workflow.md (ещё не мигрирован в OpenSpec — он остаётся источником истины по жизненному циклу). Сверка реальности с БД (capability state-reconciliation) реализована в reconcileDesync и уже исключает failed/stuck.

Текущее поведение, породившее инцидент:

• checkTimeouts (worker.go:268-285) меряет возраст задачи от created_at и при metaDL дольше magnet_timeout гонит в failed/magnet_timeout. Дефолт magnet_timeout = 30m (config.go:184), но для долгих magnet это слишком агрессивно.
• failed/stuck терминальны, выхода нет; transition уведомляет только review/done/orphaned/target_missing (worker.go:301-312) — падение молчит.
• Worker.Retry (worker.go:348-373) возвращает в downloading, но базис таймаута (created_at) не меняется → checkTimeouts роняет задачу снова на ближайшем тике; retry экспонирован только в REST.

qbt.Torrent уже содержит AddedOn (unix, секунды) — время добавления торрента в qBittorrent.

Goals / Non-Goals

Goals:

• Долгий metaDL не убивается агрессивно; magnet_timeout — редкий страховочный предохранитель (дефолт 24h), а не рабочий механизм.
• Корректный базис таймаута — от факта в qBittorrent (added_on), не от created_at.
• Любой переход в failed/stuck уведомляет автора.
• Авто-восстановление задач, упавших по нашей нетерпеливости (magnet_timeout/stalled), когда источник в qBittorrent ожил и продвинулся.
• Ручной retry в веб-UI и Telegram; перецепление к живому торренту вместо слепого повторного Add.

Non-Goals:

• Не воскрешаем реальные/пользовательские провалы: qbit_error, reverted, cancelled, deleted.
• Не трогаем сам торрент в qBittorrent при падении (источник неприкосновенен).
• Без миграций БД и без новых внешних зависимостей.
• Не вводим отдельную capability notifications — преждевременно.

Decisions

1. Базис таймаута — added_on, а не created_at

checkTimeouts считает age = now - torrent.AddedOn (UTC). Это чинит неверный отсчёт для усыновлённых раздач и — главное — делает retry/восстановление устойчивым: после возврата в downloading базис не сбрасывается в «сейчас», он привязан к реальному возрасту торрента. Отдельный сброс created_at при Retry больше не нужен.

Альтернатива: хранить «время входа в metaDL» отдельным полем БД — точнее, но требует миграции и записи на каждый тик. added_on достаточно (огрубление в большую сторону безопасно при 24h-предохранителе).

2. Дефолт magnet_timeout → 24h

Меняем дефолт в config.go и config.example.toml. Реальные провалы ловятся классом classErrored (error/missingFiles → qbit_error) — это уже работает и не зависит от wall-clock. У qBittorrent нет статуса «magnet мёртв», поэтому большой страховочный таймаут — единственный сигнал на безнадёжный magnet.

3. Уведомление о падении

В transition добавляем ветки для StateFailed и StateStuck → новый EventFailed. Сообщение в notifier (tgbot/httpapi) читает состояние и error_code задачи и формирует текст. Один Event на оба состояния — дробить на EventStuck смысла нет (различие видно из error_code).

4. Авто-восстановление в сверке

Отдельный проход reconcileRecovery (рядом с reconcileDesync, под w.mu, из Poll): берём задачи в failed/stuck с восстановимым error_code (magnet_timeout/stalled), находим их торрент в уже построенном индексе byHash. Воскрешаем только если торрент продвинулся за условие падения:

• magnet_timeout: восстанавливаем, когда !isMeta(state) и не classErrored (метаданные получены);
• stalled: восстанавливаем, когда !isStalledDL(state) и не classErrored (раздача ожила).

Иначе (торрент всё ещё в metaDL/stalledDL, либо отсутствует) — оставляем как есть. Это критично против зацикливания: при 24h-предохранителе мёртвый magnet, упавший по таймауту, остаётся в metaDL; без проверки прогресса восстановление вернуло бы его в downloading, и он падал бы снова каждые 24ч.

Целевое состояние выводим из classify(state): classReady → completed, classDownloading → downloading. При возврате в downloading восстанавливаем idempotency_key = infohash (нужен метод стора, т.к. SetDownloadState его при терминальном переходе снимает), чтобы повторный приём снова дедуплицировался.

Альтернатива: расширить reconcileDesync матрицей «источник × цель». Не подходит: у failed/stuck нет разложенной цели, ось другая (прогресс источника), отдельный проход чище.

5. Починка Worker.Retry + кнопки в UI/Telegram

Retry: если торрент задачи уже есть в qBittorrent (живой) — не делаем повторный Add, только переводим в downloading и восстанавливаем idempotency_key; Add выполняем, только когда раздачи нет. Базис таймаута теперь added_on, поэтому немедленного повторного падения нет (корень бага устранён решением 1). В internal/httpapi (веб-UI) и internal/tgbot добавляем действие retry рядом с существующим Cancel, вызывающее тот же Worker.Retry.

6. error_code в именованные константы

Строки "magnet_timeout", "stalled", "qbit_error", "qbit_add" выносим в именованные константы (рядом с состояниями в store или в worker), чтобы проверка восстановимости (magnet_timeout/stalled) и присвоение не расходились по литералам. Требует, чтобы error_code задачи был доступен из store.Download (проверить наличие поля; при отсутствии — добавить чтение, без миграции, столбец уже есть).

Risks / Trade-offs

• Флаппинг уведомлений (fail → восстановление → fail) → при дефолте 24h и условии «торрент продвинулся» падение и воскрешение редки; повторный fail возможен только если раздача снова реально застрянет. Доп. дебаунс не вводим — усложнение без явной нужды.
• Базис added_on огрубляет (re-add торрента сбрасывает возраст) → при 24h-предохранителе и авто-восстановлении это не приводит к ложным провалам; ранее проблема была в 30m-агрессии, которую и убираем.
• magnet_timeout всё ещё может ложно сработать на очень медленном, но живом magnet (>24h до метаданных) → теперь это не тупик: уведомление + при получении метаданных авто-восстановление вернёт задачу, плюс есть ручной retry.
• idempotency_key восстановление при воскрешении: если за время в failed пользователь успел повторно принять тот же infohash и завести новую задачу, ключ уже занят. Обрабатываем как конфликт (не воскрешаем старую либо логируем и оставляем в failed) — уточнить в реализации.

Migration Plan

Изменение поведения + конфига, без миграций БД и без слома API. Деплой — обычный (новый бинарь на umbar). Дефолт magnet_timeout меняется; явное значение в существующем config.toml сохраняет поведение пользователя. Откат — предыдущий бинарь; данные совместимы.

Open Questions

Решены на ревью дизайна:

• Занятый idempotency_key при авто-восстановлении → старую задачу не воскрешаем, оставляем в failed и логируем конфликт.
• Уведомление об успешном авто-восстановлении → не шлём, достаточно лога.