Быстрый приём: сохранение в catched, добавление в qBittorrent — шаг worker'а

Приём (Ingest) стал быстрым: синхронно только парс magnet, синтез контекста из
полей ссылки, атомарный дедуп и запись загрузки в новое состояние `catched` —
ответ клиенту сразу. Медленный вывод имени (LLM) и добавление в qBittorrent
вынесены в асинхронный шаг машины состояний, который двигает worker.

- store: состояние `catched` (нетерминальное, активная группа); атомарный
  переход PromoteCatched (catched → downloading + display_name) с гардом
  state='catched' (ре-валидация после сетевых вызовов вне блокировки)
- ingest: убраны namer/qbt из пути приёма; пишем `catched`, отвечаем сразу
- worker.processCatched: вне w.mu выводит имя и qbt.Add, под w.mu — короткий
  переход; сбой add оставляет catched (ретрай тиком); предохранитель
  catch_timeout → failed(qbit_add)+notify; catched исключён из проверок пропажи
- config: worker.catch_timeout (дефолт 10m)
- веб-UI: бейдж catched, активная группа, самозавершающийся htmx-поллинг
  карточки/страницы до перехода в downloading; Telegram-текст без сырого catched
- OpenSpec: дельты ingest/download-tracking/web-ui влиты в спеки, change
  заархивирован

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

internal/worker/catched_test.go

@@ -0,0 +1,152 @@
+package worker
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"git.vakhrushev.me/av/jellybit/internal/store"
+)
+
+// fakeNamer — вывод имени для шага добавления. onCall позволяет вклиниться в
+// момент (медленного) вывода имени, симулируя параллельную отмену.
+type fakeNamer struct {
+	name       string
+	gotContext string
+	onCall     func()
+}
+
+func (f *fakeNamer) DeriveName(_ context.Context, contextText, _ string) string {
+	f.gotContext = contextText
+	if f.onCall != nil {
+		f.onCall()
+	}
+	return f.name
+}
+
+func catchedStore(id, infohash, createdAt, ctxText string) *fakeStore {
+	return &fakeStore{downloads: map[string]*store.Download{
+		id: {
+			ID:         id,
+			State:      store.StateCatched,
+			SourceType: store.SourceMagnet,
+			SourceRef:  "magnet:?xt=urn:btih:" + infohash + "&dn=Dune",
+			Infohashes: hashesOf(id, infohash),
+			Context:    ctxText,
+			CreatedAt:  createdAt,
+		},
+	}}
+}
+
+const catchedIH = "541adcff3b6dd5dba7088ea83317d9d6fac331d6"
+
+// now воркера в тестах — 2026-06-14 10:00 UTC (см. newTestWorker).
+var nowStr = store.FormatTime(time.Date(2026, 6, 14, 10, 0, 0, 0, time.UTC))
+
+// Успех: выводим имя, добавляем в qBit с rename, переводим catched → downloading
+// и сохраняем display_name.
+func TestProcessCatchedAddsToQbit(t *testing.T) {
+	st := catchedStore("1", catchedIH, nowStr, "Дюна 2")
+	qb := &fakeQbt{}
+	w := newTestWorker(st, qb)
+	nm := &fakeNamer{name: "Дюна: Часть вторая (2024)"}
+	w.SetNamer(nm)
+
+	w.processCatched(context.Background())
+
+	if len(qb.added) != 1 {
+		t.Fatalf("qbt.Add calls = %d, want 1", len(qb.added))
+	}
+	add := qb.added[0]
+	if add.Rename != "Дюна: Часть вторая (2024)" {
+		t.Errorf("rename = %q", add.Rename)
+	}
+	if add.Category != "jellybit" || add.URLs[0] != st.downloads["1"].SourceRef {
+		t.Errorf("add = %+v", add)
+	}
+	if nm.gotContext != "Дюна 2" {
+		t.Errorf("namer получил контекст %q", nm.gotContext)
+	}
+	d := st.downloads["1"]
+	if d.State != store.StateDownloading {
+		t.Errorf("state = %q, want downloading", d.State)
+	}
+	if d.DisplayName != "Дюна: Часть вторая (2024)" {
+		t.Errorf("display_name = %q", d.DisplayName)
+	}
+}
+
+// Транзиентный сбой add — остаёмся в catched для повтора на следующем тике.
+func TestProcessCatchedTransientFailureKeepsCatched(t *testing.T) {
+	st := catchedStore("1", catchedIH, nowStr, "ctx")
+	qb := &fakeQbt{addErr: errors.New("connection refused")}
+	w := newTestWorker(st, qb)
+	w.SetNamer(&fakeNamer{name: "X"})
+
+	w.processCatched(context.Background())
+
+	if st.downloads["1"].State != store.StateCatched {
+		t.Errorf("state = %q, want catched (повтор)", st.downloads["1"].State)
+	}
+}
+
+// Предохранитель: catched старше catch_timeout → failed (qbit_add) + уведомление;
+// add при этом не вызывается.
+func TestProcessCatchedTimeoutFails(t *testing.T) {
+	old := store.FormatTime(time.Date(2026, 6, 14, 9, 0, 0, 0, time.UTC)) // 1 час до now
+	st := catchedStore("1", catchedIH, old, "ctx")
+	qb := &fakeQbt{}
+	w := newTestWorker(st, qb)
+	w.cfg.CatchTimeout = 10 * time.Minute
+	n := &recordingNotifier{ch: make(chan notifyEvent, 1)}
+	w.SetNotifier(n)
+
+	w.processCatched(context.Background())
+
+	d := st.downloads["1"]
+	if d.State != store.StateFailed || d.ErrorCode.String != errCodeQbitAdd {
+		t.Errorf("state = %q code = %q, want failed/qbit_add", d.State, d.ErrorCode.String)
+	}
+	if len(qb.added) != 0 {
+		t.Errorf("add не должен вызываться при таймауте, calls = %d", len(qb.added))
+	}
+	if e := waitNotify(t, n); e.ev != EventFailed {
+		t.Errorf("событие = %q, want failed", e.ev)
+	}
+}
+
+// Ре-валидация: если во время сетевых вызовов (вне блокировки) задачу отменили,
+// переход в downloading не применяется — состояние остаётся cancelled.
+func TestProcessCatchedCancelledDuringAddSkipsPromote(t *testing.T) {
+	st := catchedStore("1", catchedIH, nowStr, "ctx")
+	qb := &fakeQbt{}
+	w := newTestWorker(st, qb)
+	// namer имитирует параллельную отмену во время (медленного) вывода имени.
+	nm := &fakeNamer{name: "X", onCall: func() { st.downloads["1"].State = store.StateCancelled }}
+	w.SetNamer(nm)
+
+	w.processCatched(context.Background())
+
+	if len(qb.added) != 1 {
+		t.Fatal("add должен был вызваться (сеть идёт вне замка)")
+	}
+	if st.downloads["1"].State != store.StateCancelled {
+		t.Errorf("ре-валидация не сработала: state = %q, want cancelled", st.downloads["1"].State)
+	}
+}
+
+// Поллинг активных (downloading) не трогает catched: раздачи в qBittorrent у
+// пойманной загрузки ещё нет по дизайну, это не «пропажа».
+func TestPollIgnoresCatched(t *testing.T) {
+	st := catchedStore("1", catchedIH, nowStr, "ctx")
+	qb := &fakeQbt{} // раздач нет
+	w := newTestWorker(st, qb)
+
+	if err := w.Poll(context.Background()); err != nil {
+		t.Fatalf("Poll: %v", err)
+	}
+	if st.downloads["1"].State != store.StateCatched {
+		t.Errorf("catched тронут поллингом: %q", st.downloads["1"].State)
+	}
+}

internal/worker/review_test.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"fmt"
 	"io"
 	"log/slog"
 	"os"
@@ -346,6 +347,16 @@ func (m *memStore) SetDownloadState(_ context.Context, id string, st store.State
 	return nil
 }
 
+func (m *memStore) PromoteCatched(_ context.Context, id, displayName string) error {
+	d, ok := m.downloads[id]
+	if !ok || d.State != store.StateCatched {
+		return fmt.Errorf("promote catched %s: not in catched", id)
+	}
+	d.State = store.StateDownloading
+	d.DisplayName = displayName
+	return nil
+}
+
 func (m *memStore) SetSourceMissCount(_ context.Context, id string, n int) error {
 	if d, ok := m.downloads[id]; ok {
 		d.SourceMissCount = n

internal/worker/worker.go

@@ -24,6 +24,7 @@ import (
 	"git.vakhrushev.me/av/jellybit/internal/ident"
 	"git.vakhrushev.me/av/jellybit/internal/layout"
 	"git.vakhrushev.me/av/jellybit/internal/logctx"
+	"git.vakhrushev.me/av/jellybit/internal/magnet"
 	"git.vakhrushev.me/av/jellybit/internal/qbt"
 	"git.vakhrushev.me/av/jellybit/internal/recognize"
 	"git.vakhrushev.me/av/jellybit/internal/store"
@@ -44,6 +45,9 @@ type Store interface {
 	ListRecoverable(ctx context.Context, codes ...string) ([]store.Download, error)
 	GetDownload(ctx context.Context, id string) (*store.Download, error)
 	SetDownloadState(ctx context.Context, id string, state store.State, errCode, errMsg string) error
+	// PromoteCatched атомарно переводит catched → downloading с записью имени
+	// (гард state='catched' — ре-валидация после сетевых вызовов вне блокировки).
+	PromoteCatched(ctx context.Context, id, displayName string) error
 	SetSourceMissCount(ctx context.Context, id string, n int) error
 	SetSourceAddedAt(ctx context.Context, id string, t time.Time) error
 
@@ -85,6 +89,12 @@ type Recognizer interface {
 	Recognize(ctx context.Context, in recognize.Input) (recognize.Result, error)
 }
 
+// Namer выводит человекочитаемое отображаемое имя из контекста (naming.Namer).
+// Пустой результат → rename в qBittorrent не задаём. nil → имя не выводим.
+type Namer interface {
+	DeriveName(ctx context.Context, contextText, hint string) string
+}
+
 // Layouter — раскладчик хардлинками (layout.Layouter).
 type Layouter interface {
 	BuildLinks(p layout.Plan) ([]layout.Link, error)
@@ -111,6 +121,10 @@ const (
 	errCodeMagnetTimeout = "magnet_timeout"
 	errCodeStalled       = "stalled"
 	errCodeQbitError     = "qbit_error"
+	// errCodeQbitAdd — не удалось добавить пойманную загрузку в qBittorrent за
+	// catch_timeout (устойчивая недоступность qBit). Раздачи в qBittorrent нет,
+	// восстановлению сверкой не подлежит.
+	errCodeQbitAdd = "qbit_add"
 )
 
 // Notifier — исходящие пинги (Telegram). Вызывается неблокирующе.
@@ -134,6 +148,7 @@ type Config struct {
 	PollInterval  time.Duration
 	StuckAfter    time.Duration // stalledDL дольше → stuck
 	MagnetTimeout time.Duration // metaDL дольше → failed
+	CatchTimeout  time.Duration // catched дольше (не удалось добавить в qBit) → failed
 	// SourceMissingThreshold — порог дебаунса пропажи источника (тиков сверки).
 	// <1 трактуется как 1 (помечаем при первой же устойчивой пропаже).
 	SourceMissingThreshold int
@@ -181,6 +196,7 @@ type Worker struct {
 	qbt        QBittorrent
 	recognizer Recognizer
 	layouter   Layouter
+	namer      Namer // опц. вывод отображаемого имени на шаге добавления catched
 	cfg        Config
 	log        *slog.Logger
 
@@ -209,6 +225,10 @@ type Worker struct {
 // одной задачи (см. failNotified).
 const failNotifyDebounce = time.Hour
 
+// SetNamer подключает вывод отображаемого имени для шага добавления catched
+// (до запуска Run). nil → имя не выводим, добавляем без rename.
+func (w *Worker) SetNamer(n Namer) { w.namer = n }
+
 // SetNotifier подключает исходящие пинги (до запуска Run).
 func (w *Worker) SetNotifier(n Notifier) { w.notifier = n }
 
@@ -291,12 +311,95 @@ func (w *Worker) pollOnce(ctx context.Context) {
 	if err := w.Poll(ctx); err != nil {
 		w.log.Warn("poll failed", "error", err)
 	}
+	// Быстрый приём отложил добавление в qBittorrent: подхватываем пойманные
+	// (catched) загрузки и добавляем их (сеть — вне блокировки переходов).
+	w.processCatched(ctx)
 	// Ф3: распознаём завершённые загрузки (и перезапускаем по подсказке).
 	if w.recognizer != nil {
 		w.recognizePending(ctx)
 	}
 }
 
+// processCatched — асинхронный шаг добавления пойманных загрузок в qBittorrent.
+// Для каждой catched: (предохранитель) если висит дольше catch_timeout — уводим
+// в failed; иначе выводим имя и добавляем в qBit. Медленные вызовы (LLM-namer,
+// qbt.Add) идут ВНЕ w.mu, чтобы не задерживать команды транспортов и поллинг;
+// под w.mu берутся только короткие DB-переходы (с ре-валидацией state=catched).
+func (w *Worker) processCatched(ctx context.Context) {
+	w.mu.Lock()
+	catched, err := w.store.ListDownloadsByState(ctx, store.StateCatched)
+	w.mu.Unlock()
+	if err != nil {
+		w.log.Warn("list catched failed", "capability", capIngest, "error", err)
+		return
+	}
+	for _, d := range catched {
+		cctx := w.scoped(ctx, capIngest, d.ID, d.PrimaryInfohash())
+
+		// Предохранитель: устойчивая невозможность добавить в qBittorrent.
+		if w.cfg.CatchTimeout > 0 {
+			if age, ok := w.catchedAge(d); ok && age > w.cfg.CatchTimeout {
+				w.mu.Lock()
+				// Ре-валидация под замком: список catched снят раньше, задачу
+				// могли отменить (catched → cancelled) в это окно — тогда failed
+				// не навязываем (иначе затёрли бы cancelled и слали лишний пинг).
+				if cur, err := w.store.GetDownload(cctx, d.ID); err == nil && cur.State == store.StateCatched {
+					w.transition(cctx, d, store.StateFailed, errCodeQbitAdd,
+						fmt.Sprintf("not added to qBittorrent after %s", age.Truncate(time.Second)))
+				}
+				w.mu.Unlock()
+				continue
+			}
+		}
+
+		// Вне w.mu: вывод имени (потенциально медленный LLM) и добавление.
+		var rename string
+		if w.namer != nil {
+			hint := ""
+			if info, perr := magnet.Parse(d.SourceRef); perr == nil {
+				hint = info.DisplayName
+			}
+			rename = w.namer.DeriveName(cctx, d.Context, hint)
+		}
+		addErr := w.qbt.Add(cctx, qbt.AddRequest{
+			URLs:     []string{d.SourceRef},
+			Category: w.cfg.Category,
+			SavePath: w.cfg.SavePath,
+			Rename:   rename,
+		})
+		if addErr != nil {
+			// Транзиентный сбой (qBit недоступен) — остаёмся в catched, повтор на
+			// следующем тике. Поведение вызова qBit уже залогировал клиент (ext.*).
+			logctx.From(cctx).Warn("catched add to qbittorrent failed, will retry", "error", addErr)
+			continue
+		}
+
+		// Успех: короткий переход под w.mu с ре-валидацией state=catched
+		// (загрузку могли отменить, пока шли сетевые вызовы).
+		w.mu.Lock()
+		if err := w.store.PromoteCatched(cctx, d.ID, rename); err != nil {
+			logctx.From(cctx).Info("catched promote skipped", "reason", err.Error())
+		} else {
+			logctx.From(cctx).Info("state transition", "from", store.StateCatched,
+				"to", store.StateDownloading)
+		}
+		w.mu.Unlock()
+	}
+}
+
+// catchedAge — возраст пойманной загрузки от created_at (у catched раздачи в
+// qBittorrent ещё нет, added_on недоступен). ok=false — created_at не разобрать.
+func (w *Worker) catchedAge(d store.Download) (time.Duration, bool) {
+	created, err := d.CreatedTime()
+	if err != nil {
+		w.log.Warn("cannot determine catched age",
+			"capability", capIngest, "download_id", d.ID,
+			"created_at", d.CreatedAt, "error", err)
+		return 0, false
+	}
+	return w.now().Sub(created), true
+}
+
 // Poll сверяет активные задачи с состоянием qBittorrent и двигает их.
 // Листаем все торренты (а не только свою категорию), чтобы reconcile нашёл и
 // усыновлённые по тегу раздачи, а discovery — увидел новые.

internal/worker/worker_test.go

@@ -163,6 +163,20 @@ func (f *fakeStore) SetDownloadState(_ context.Context, id string, st store.Stat
 	return nil
 }
 
+func (f *fakeStore) PromoteCatched(_ context.Context, id, displayName string) error {
+	d, ok := f.downloads[id]
+	if !ok {
+		return fmt.Errorf("download %s not found", id)
+	}
+	if d.State != store.StateCatched {
+		return fmt.Errorf("promote catched %s: not in catched (%s)", id, d.State)
+	}
+	d.State = store.StateDownloading
+	d.DisplayName = displayName
+	f.transitions = append(f.transitions, transition{id, store.StateDownloading})
+	return nil
+}
+
 func (f *fakeStore) SetSourceMissCount(_ context.Context, id string, n int) error {
 	d, ok := f.downloads[id]
 	if !ok {