feat(adapters): qBittorrent, filesystem, TMDB and Emby adapters with testkit mocks (W1-3a)
- qbittorrent: WebUI API v2 client (cookie/API-key auth, add/info/files/filePrio, pause/resume with 5.x stop/start fallback, tags, delete with explicit deleteFiles, maindata), error classes, idempotent submit with local infohash (own bencode) and post-timeout hash/probe-tag lookup; state mapping per MoviePilot - fs: copyWithVerify (tmp + fsync + size/sha256/sample + no-clobber commit), moveSafe (EXDEV surfaced), resumable crossDeviceMove, statSafe/checkRoot with root sentinel, budgeted incremental scan with cursor, ffprobe, statfs usage - tmdb: multi-language search/details/seasons, LRU+TTL cache with coalescing, rate-limit backoff, MoviePilot match chain (name normalization, year +-1) - emby: Emby/Jellyfin items/seasons/episodes/MediaSources, failures -> unknown - testkit: mock qB / TMDB / Emby servers, torrent builder, temp-tree fixtures - docs: W1-3a porting table appended to downloader-and-sites ledger Co-Authored-By: Claude Fable 5.1 <[email protected]>
This commit is contained in:
rootandClaude Fable 5.1 committed
1 parent
9c881e737f
commit
ef2e504a94
45 files changed
+5766
-1
No files matched your search
@@ -0,0 +1,754 @@
|
||||
/**
|
||||
* qBittorrent WebUI API v2 客户端。
|
||||
* 迁移来源:MoviePilot app/modules/qbittorrent/qbittorrent.py(e6820a8),逐函数对照见
|
||||
* docs/porting/moviepilot-downloader-and-sites.md「W1-3a 实际迁移对照」。
|
||||
* 叠加:多实例、错误分类(DownloaderError)、提交幂等(本地 infohash 预查 + 收单超时按 hash 回查)。
|
||||
*/
|
||||
import { randomBytes } from "node:crypto";
|
||||
import { DownloaderError, type DownloaderErrorKind } from "./errors";
|
||||
import { isDownloadComplete, mapQbState, type QbObservedState } from "./state";
|
||||
import { BencodeError, parseMagnet, parseTorrent } from "./torrent";
|
||||
|
||||
export interface QbInstanceConfig {
|
||||
/** 本系统内的下载器实例 ID(downloader_instance.id) */
|
||||
instanceId: string;
|
||||
/** 例:http://127.0.0.1:8080(不带 /api/v2) */
|
||||
baseUrl: string;
|
||||
username?: string;
|
||||
password?: string;
|
||||
/** qB 5.2+ WebUI API Key;有则走 Bearer,不登录 */
|
||||
apiKey?: string;
|
||||
/** 单次请求超时,默认 15000 */
|
||||
timeoutMs?: number;
|
||||
/** 幂等读请求的重试次数(不含首次),默认 2;写请求不自动重试 */
|
||||
retries?: number;
|
||||
/** 重试退避基数,指数增长,默认 300ms */
|
||||
retryBaseMs?: number;
|
||||
/** 提交后按 infohash/探针标签回查的次数与间隔,默认 9 次 × 3000ms(对照 MP get_torrent_id_by_tag;首查不等待) */
|
||||
lookup?: { attempts: number; intervalMs: number };
|
||||
/** 探针标签前缀,默认 uhd-probe- */
|
||||
probeTagPrefix?: string;
|
||||
/** 实例级默认:顺序下载 / 首尾块优先(对照 MP sequentail / first_last_piece 配置) */
|
||||
sequentialDownload?: boolean;
|
||||
firstLastPiecePrio?: boolean;
|
||||
/** 注入 fetch(测试/代理) */
|
||||
fetch?: typeof fetch;
|
||||
}
|
||||
|
||||
export interface QbTorrent {
|
||||
instanceId: string;
|
||||
hash: string;
|
||||
infohashV1: string | null;
|
||||
infohashV2: string | null;
|
||||
name: string;
|
||||
rawState: string;
|
||||
state: QbObservedState;
|
||||
/** 严格完成判定结果(progress>=1 && amountLeft<=0 && 终态) */
|
||||
complete: boolean;
|
||||
progress: number;
|
||||
amountLeft: number;
|
||||
size: number;
|
||||
totalSize: number | null;
|
||||
savePath: string;
|
||||
contentPath: string | null;
|
||||
category: string;
|
||||
tags: string[];
|
||||
addedOn: number | null;
|
||||
completionOn: number | null;
|
||||
dlspeed: number;
|
||||
upspeed: number;
|
||||
eta: number | null;
|
||||
ratio: number | null;
|
||||
seedingTimeSec: number | null;
|
||||
}
|
||||
|
||||
export interface QbFile {
|
||||
index: number;
|
||||
name: string;
|
||||
size: number;
|
||||
progress: number;
|
||||
/** 0 不下载,1 普通,6 高,7 最高 */
|
||||
priority: number;
|
||||
isSeed: boolean | null;
|
||||
}
|
||||
|
||||
export type TorrentSource =
|
||||
| { kind: "magnet"; uri: string }
|
||||
| { kind: "url"; url: string }
|
||||
| { kind: "file"; bytes: Uint8Array; filename?: string };
|
||||
|
||||
export interface AddTorrentRequest {
|
||||
source: TorrentSource;
|
||||
savePath: string;
|
||||
category?: string;
|
||||
tags?: string[];
|
||||
paused?: boolean;
|
||||
rename?: string;
|
||||
contentLayout?: "Original" | "Subfolder" | "NoSubfolder";
|
||||
sequential?: boolean;
|
||||
firstLastPiecePrio?: boolean;
|
||||
}
|
||||
|
||||
export interface AddTorrentResult {
|
||||
accepted: boolean;
|
||||
addedIds: string[];
|
||||
raw: string;
|
||||
}
|
||||
|
||||
export type SubmitOutcome =
|
||||
| { kind: "added"; hash: string; via: "confirmed" | "added_ids" | "probe_tag" | "recovered_after_timeout" }
|
||||
| { kind: "already_exists"; hash: string; existing: QbTorrent }
|
||||
/** 下载器已接收(或可能已接收),但回查窗口内未找到任务;调用方稍后按 hash/probeTag 对账,不得盲目重提 */
|
||||
| { kind: "accepted_unconfirmed"; hash: string | null; probeTag: string | null }
|
||||
| { kind: "rejected"; reason: string; hash: string | null }
|
||||
/** 确认未提交成功(回查未命中且无歧义)或下载器不可达;有 hash 时用同一 hash 重试是幂等的 */
|
||||
| { kind: "unreachable"; error: DownloaderError; hash: string | null };
|
||||
|
||||
export interface TorrentQuery {
|
||||
hashes?: string[];
|
||||
tag?: string;
|
||||
/** 须同时具备的标签(对照 MP get_torrents 的 tags 子集判断);第一个走 qB 原生 tag 参数 */
|
||||
tags?: string[];
|
||||
category?: string;
|
||||
filter?:
|
||||
| "all"
|
||||
| "downloading"
|
||||
| "seeding"
|
||||
| "completed"
|
||||
| "paused"
|
||||
| "stopped"
|
||||
| "active"
|
||||
| "inactive"
|
||||
| "stalled"
|
||||
| "errored";
|
||||
}
|
||||
|
||||
export interface QbMainData {
|
||||
rid: number;
|
||||
fullUpdate: boolean;
|
||||
torrents: Record<string, Record<string, unknown>>;
|
||||
torrentsRemoved: string[];
|
||||
serverState: Record<string, unknown> | null;
|
||||
}
|
||||
|
||||
/** 下载器端口(实例维度)。上层 tasks/agent 只依赖此接口。 */
|
||||
export interface DownloaderClient {
|
||||
readonly instanceId: string;
|
||||
version(): Promise<{ app: string; webApi: string }>;
|
||||
add(req: AddTorrentRequest): Promise<AddTorrentResult>;
|
||||
submit(req: AddTorrentRequest): Promise<SubmitOutcome>;
|
||||
list(q?: TorrentQuery): Promise<QbTorrent[]>;
|
||||
/** 严格完成判定后的已完成任务(对照 get_completed_torrents) */
|
||||
getCompleted(q?: Pick<TorrentQuery, "hashes" | "tags">): Promise<QbTorrent[]>;
|
||||
getDownloading(q?: Pick<TorrentQuery, "hashes" | "tags">): Promise<QbTorrent[]>;
|
||||
findByHash(hash: string): Promise<QbTorrent | null>;
|
||||
files(hash: string, opts?: { retries?: number; intervalMs?: number }): Promise<QbFile[]>;
|
||||
/** priority 0 不下载;fileIds 为空返回 false 且不发请求(对照 set_files) */
|
||||
setFilePriority(hash: string, fileIds: number[], priority: 0 | 1 | 6 | 7): Promise<boolean>;
|
||||
setForceStart(hashes: string[], enable?: boolean): Promise<void>;
|
||||
recheck(hashes: string[]): Promise<void>;
|
||||
setLocation(hashes: string[], location: string): Promise<void>;
|
||||
setCategory(hashes: string[], category: string): Promise<void>;
|
||||
changeTorrent(hash: string, opts: TorrentLimits): Promise<void>;
|
||||
/** 只读下载器全局偏好(不改写,见 QA6) */
|
||||
preferences(): Promise<Record<string, unknown>>;
|
||||
contentLayout(): Promise<"Original" | "Subfolder" | "NoSubfolder">;
|
||||
transferInfo(): Promise<Record<string, unknown>>;
|
||||
pause(hashes: string[]): Promise<void>;
|
||||
resume(hashes: string[]): Promise<void>;
|
||||
addTags(hashes: string[], tags: string[]): Promise<void>;
|
||||
removeTags(hashes: string[], tags: string[]): Promise<void>;
|
||||
deleteTagDefinitions(tags: string[]): Promise<void>;
|
||||
/** 从任务移除标签并删除全局定义;hashes 为 null 时只删定义(对照 delete_torrents_tag) */
|
||||
deleteTorrentsTag(hashes: string[] | null, tags: string[]): Promise<void>;
|
||||
/** deleteFiles 必须显式给出;删数据前的引用检查由上层 assertSafeToDeleteData 负责 */
|
||||
delete(hashes: string[], opts: { deleteFiles: boolean }): Promise<void>;
|
||||
mainData(rid?: number): Promise<QbMainData>;
|
||||
}
|
||||
|
||||
export interface TorrentLimits {
|
||||
/** KB/s,0 不限速 */
|
||||
uploadLimitKBps?: number;
|
||||
downloadLimitKBps?: number;
|
||||
ratioLimit?: number;
|
||||
/** 分钟 */
|
||||
seedingTimeLimitMin?: number;
|
||||
}
|
||||
|
||||
type Body = { kind: "form"; data: Record<string, string> } | { kind: "multipart"; data: FormData };
|
||||
|
||||
interface ReqOpts {
|
||||
query?: Record<string, string | undefined>;
|
||||
body?: Body;
|
||||
idempotent: boolean;
|
||||
}
|
||||
|
||||
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
|
||||
|
||||
function num(v: unknown): number | null {
|
||||
return typeof v === "number" && Number.isFinite(v) ? v : null;
|
||||
}
|
||||
function str(v: unknown): string | null {
|
||||
return typeof v === "string" && v !== "" ? v : null;
|
||||
}
|
||||
|
||||
export function normalizeTorrent(instanceId: string, r: Record<string, unknown>): QbTorrent {
|
||||
const rawState = typeof r.state === "string" ? r.state : "";
|
||||
const progress = num(r.progress) ?? 0;
|
||||
const amountLeft = num(r.amount_left) ?? Number.POSITIVE_INFINITY;
|
||||
const tags =
|
||||
typeof r.tags === "string"
|
||||
? r.tags
|
||||
.split(",")
|
||||
.map((t) => t.trim())
|
||||
.filter(Boolean)
|
||||
: [];
|
||||
return {
|
||||
instanceId,
|
||||
hash: String(r.hash ?? "").toLowerCase(),
|
||||
infohashV1: str(r.infohash_v1),
|
||||
infohashV2: str(r.infohash_v2),
|
||||
name: String(r.name ?? ""),
|
||||
rawState,
|
||||
state: mapQbState(rawState),
|
||||
complete: isDownloadComplete({ progress, amountLeft, state: rawState }),
|
||||
progress,
|
||||
amountLeft,
|
||||
size: num(r.size) ?? 0,
|
||||
totalSize: num(r.total_size),
|
||||
savePath: String(r.save_path ?? ""),
|
||||
contentPath: str(r.content_path),
|
||||
category: String(r.category ?? ""),
|
||||
tags,
|
||||
addedOn: num(r.added_on),
|
||||
completionOn: (num(r.completion_on) ?? -1) > 0 ? num(r.completion_on) : null,
|
||||
dlspeed: num(r.dlspeed) ?? 0,
|
||||
upspeed: num(r.upspeed) ?? 0,
|
||||
eta: num(r.eta),
|
||||
ratio: num(r.ratio),
|
||||
seedingTimeSec: num(r.seeding_time),
|
||||
};
|
||||
}
|
||||
|
||||
export class QbClient implements DownloaderClient {
|
||||
readonly instanceId: string;
|
||||
private readonly base: string;
|
||||
private readonly timeoutMs: number;
|
||||
private readonly retries: number;
|
||||
private readonly retryBaseMs: number;
|
||||
private readonly lookup: { attempts: number; intervalMs: number };
|
||||
private readonly probePrefix: string;
|
||||
private readonly fetchImpl: typeof fetch;
|
||||
private sid: string | null = null;
|
||||
private loginInFlight: Promise<void> | null = null;
|
||||
/** qB 5.x 把 pause/resume 改名为 stop/start;探测到后缓存 */
|
||||
private legacyPauseApi: boolean | null = null;
|
||||
|
||||
constructor(private readonly cfg: QbInstanceConfig) {
|
||||
this.instanceId = cfg.instanceId;
|
||||
this.base = cfg.baseUrl.replace(/\/+$/, "");
|
||||
this.timeoutMs = cfg.timeoutMs ?? 15_000;
|
||||
this.retries = cfg.retries ?? 2;
|
||||
this.retryBaseMs = cfg.retryBaseMs ?? 300;
|
||||
this.lookup = cfg.lookup ?? { attempts: 9, intervalMs: 3000 };
|
||||
this.probePrefix = cfg.probeTagPrefix ?? "uhd-probe-";
|
||||
this.fetchImpl = cfg.fetch ?? fetch;
|
||||
}
|
||||
|
||||
private err(kind: DownloaderErrorKind, message: string, endpoint: string, status?: number, cause?: unknown) {
|
||||
return new DownloaderError(kind, `[qb:${this.instanceId}] ${message}`, {
|
||||
instanceId: this.instanceId,
|
||||
endpoint,
|
||||
...(status !== undefined ? { status } : {}),
|
||||
...(cause !== undefined ? { cause } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
private async rawFetch(endpoint: string, init: RequestInit): Promise<Response> {
|
||||
try {
|
||||
return await this.fetchImpl(`${this.base}/api/v2/${endpoint}`, {
|
||||
...init,
|
||||
signal: AbortSignal.timeout(this.timeoutMs),
|
||||
});
|
||||
} catch (e) {
|
||||
const name = (e as { name?: string })?.name;
|
||||
if (name === "TimeoutError" || name === "AbortError") {
|
||||
throw this.err("timeout", `request timed out after ${this.timeoutMs}ms`, endpoint, undefined, e);
|
||||
}
|
||||
throw this.err("network", `request failed: ${(e as Error)?.message ?? String(e)}`, endpoint, undefined, e);
|
||||
}
|
||||
}
|
||||
|
||||
/** 登录;并发调用合并为一次。 */
|
||||
async login(): Promise<void> {
|
||||
if (this.cfg.apiKey) return;
|
||||
if (!this.loginInFlight) {
|
||||
this.loginInFlight = this.doLogin().finally(() => {
|
||||
this.loginInFlight = null;
|
||||
});
|
||||
}
|
||||
return this.loginInFlight;
|
||||
}
|
||||
|
||||
private async doLogin(): Promise<void> {
|
||||
const endpoint = "auth/login";
|
||||
const res = await this.rawFetch(endpoint, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/x-www-form-urlencoded", referer: this.base },
|
||||
body: new URLSearchParams({ username: this.cfg.username ?? "", password: this.cfg.password ?? "" }),
|
||||
});
|
||||
const text = await res.text();
|
||||
if (res.status === 403) throw this.err("auth", "login forbidden (IP banned after failed attempts?)", endpoint, 403);
|
||||
if (res.status === 429) throw this.err("rate", "login rate limited", endpoint, 429);
|
||||
if (!res.ok)
|
||||
throw this.err(res.status >= 500 ? "protocol" : "auth", `login HTTP ${res.status}`, endpoint, res.status);
|
||||
if (!text.trim().startsWith("Ok")) throw this.err("auth", "login rejected (bad credentials)", endpoint, res.status);
|
||||
const cookie = res.headers
|
||||
.getSetCookie()
|
||||
.map((c) => /^SID=([^;]*)/.exec(c)?.[1])
|
||||
.find((v) => v !== undefined);
|
||||
// 关闭鉴权或白名单 IP 时 qB 可能不下发 cookie,仍视为成功
|
||||
this.sid = cookie ?? "";
|
||||
}
|
||||
|
||||
private async send(endpoint: string, opts: ReqOpts): Promise<Response> {
|
||||
const attempts = opts.idempotent ? this.retries + 1 : 1;
|
||||
let lastErr: DownloaderError | null = null;
|
||||
for (let i = 0; i < attempts; i++) {
|
||||
if (i > 0) await sleep(this.retryBaseMs * 2 ** (i - 1));
|
||||
try {
|
||||
return await this.sendOnce(endpoint, opts, false);
|
||||
} catch (e) {
|
||||
if (!(e instanceof DownloaderError)) throw e;
|
||||
lastErr = e;
|
||||
const retryable = e.kind === "network" || e.kind === "timeout" || e.kind === "rate" || e.kind === "protocol";
|
||||
if (!retryable) throw e;
|
||||
}
|
||||
}
|
||||
throw lastErr!;
|
||||
}
|
||||
|
||||
private async sendOnce(endpoint: string, opts: ReqOpts, relogged: boolean): Promise<Response> {
|
||||
if (!this.cfg.apiKey && this.sid === null) await this.login();
|
||||
const headers: Record<string, string> = { referer: this.base };
|
||||
if (this.cfg.apiKey) headers.authorization = `Bearer ${this.cfg.apiKey}`;
|
||||
else if (this.sid) headers.cookie = `SID=${this.sid}`;
|
||||
let body: RequestInit["body"] | undefined;
|
||||
if (opts.body?.kind === "form") {
|
||||
headers["content-type"] = "application/x-www-form-urlencoded";
|
||||
body = new URLSearchParams(opts.body.data);
|
||||
} else if (opts.body?.kind === "multipart") {
|
||||
body = opts.body.data;
|
||||
}
|
||||
const qs = new URLSearchParams();
|
||||
for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== undefined) qs.set(k, v);
|
||||
const path = qs.size ? `${endpoint}?${qs}` : endpoint;
|
||||
const res = await this.rawFetch(path, { method: body ? "POST" : "GET", headers, ...(body ? { body } : {}) });
|
||||
const s = res.status;
|
||||
if (s === 401 || s === 403) {
|
||||
await res.body?.cancel();
|
||||
if (!this.cfg.apiKey && !relogged) {
|
||||
this.sid = null;
|
||||
await this.login();
|
||||
return this.sendOnce(endpoint, opts, true);
|
||||
}
|
||||
throw this.err("auth", `unauthorized (HTTP ${s})`, endpoint, s);
|
||||
}
|
||||
if (s === 404) {
|
||||
const t = await res.text();
|
||||
throw this.err("notfound", t || "not found", endpoint, s);
|
||||
}
|
||||
if (s === 429) {
|
||||
await res.body?.cancel();
|
||||
throw this.err("rate", "rate limited", endpoint, s);
|
||||
}
|
||||
if (s === 400 || s === 409 || s === 415) {
|
||||
const t = await res.text();
|
||||
throw this.err("rejected", t || `HTTP ${s}`, endpoint, s);
|
||||
}
|
||||
if (!res.ok) {
|
||||
await res.body?.cancel();
|
||||
throw this.err("protocol", `unexpected HTTP ${s}`, endpoint, s);
|
||||
}
|
||||
return res;
|
||||
}
|
||||
|
||||
private async json<T>(endpoint: string, query?: Record<string, string | undefined>): Promise<T> {
|
||||
const res = await this.send(endpoint, { idempotent: true, ...(query ? { query } : {}) });
|
||||
const text = await res.text();
|
||||
try {
|
||||
return JSON.parse(text) as T;
|
||||
} catch (e) {
|
||||
throw this.err("protocol", "invalid JSON response", endpoint, res.status, e);
|
||||
}
|
||||
}
|
||||
|
||||
private async post(endpoint: string, data: Record<string, string>, idempotent = true): Promise<string> {
|
||||
const res = await this.send(endpoint, { idempotent, body: { kind: "form", data } });
|
||||
return res.text();
|
||||
}
|
||||
|
||||
async version(): Promise<{ app: string; webApi: string }> {
|
||||
const app = await (await this.send("app/version", { idempotent: true })).text();
|
||||
const webApi = await (await this.send("app/webapiVersion", { idempotent: true })).text();
|
||||
return { app: app.trim(), webApi: webApi.trim() };
|
||||
}
|
||||
|
||||
async add(req: AddTorrentRequest): Promise<AddTorrentResult> {
|
||||
const form = new FormData();
|
||||
const src = req.source;
|
||||
if (src.kind === "file") {
|
||||
form.append(
|
||||
"torrents",
|
||||
new Blob([new Uint8Array(src.bytes)], { type: "application/x-bittorrent" }),
|
||||
src.filename ?? "upload.torrent",
|
||||
);
|
||||
} else {
|
||||
form.append("urls", src.kind === "magnet" ? src.uri : src.url);
|
||||
}
|
||||
form.append("savepath", req.savePath);
|
||||
if (req.category !== undefined) form.append("category", req.category);
|
||||
if (req.tags?.length) form.append("tags", req.tags.join(","));
|
||||
const paused = req.paused ? "true" : "false";
|
||||
form.append("paused", paused); // <= 4.x
|
||||
form.append("stopped", paused); // >= 5.x
|
||||
if (req.rename) form.append("rename", req.rename);
|
||||
form.append("contentLayout", req.contentLayout ?? "Original");
|
||||
form.append("autoTMM", "false");
|
||||
const seq = req.sequential ?? this.cfg.sequentialDownload;
|
||||
const flp = req.firstLastPiecePrio ?? this.cfg.firstLastPiecePrio;
|
||||
if (seq !== undefined) form.append("sequentialDownload", String(seq));
|
||||
if (flp !== undefined) form.append("firstLastPiecePrio", String(flp));
|
||||
const res = await this.send("torrents/add", { idempotent: false, body: { kind: "multipart", data: form } });
|
||||
const raw = (await res.text()).trim();
|
||||
if (raw.startsWith("{")) {
|
||||
try {
|
||||
const j = JSON.parse(raw) as {
|
||||
success_count?: number;
|
||||
pending_count?: number;
|
||||
added_torrent_ids?: string[];
|
||||
};
|
||||
const ids = (j.added_torrent_ids ?? []).map((x) => x.toLowerCase());
|
||||
return { accepted: ids.length > 0 || (j.success_count ?? 0) + (j.pending_count ?? 0) > 0, addedIds: ids, raw };
|
||||
} catch {
|
||||
// 落到文本判定
|
||||
}
|
||||
}
|
||||
return { accepted: raw.startsWith("Ok"), addedIds: [], raw };
|
||||
}
|
||||
|
||||
async list(q: TorrentQuery = {}): Promise<QbTorrent[]> {
|
||||
const need = [...(q.tag !== undefined ? [q.tag] : []), ...(q.tags ?? [])];
|
||||
const rows = await this.json<Record<string, unknown>[]>("torrents/info", {
|
||||
filter: q.filter,
|
||||
category: q.category,
|
||||
tag: need[0],
|
||||
hashes: q.hashes?.length ? q.hashes.map((h) => h.toLowerCase()).join("|") : undefined,
|
||||
});
|
||||
if (!Array.isArray(rows)) throw this.err("protocol", "torrents/info did not return an array", "torrents/info");
|
||||
const list = rows.map((r) => normalizeTorrent(this.instanceId, r));
|
||||
return need.length > 1 ? list.filter((t) => need.every((tag) => t.tags.includes(tag))) : list;
|
||||
}
|
||||
|
||||
async getCompleted(q: Pick<TorrentQuery, "hashes" | "tags"> = {}): Promise<QbTorrent[]> {
|
||||
return (await this.list({ ...q, filter: "completed" })).filter((t) => t.complete);
|
||||
}
|
||||
|
||||
async getDownloading(q: Pick<TorrentQuery, "hashes" | "tags"> = {}): Promise<QbTorrent[]> {
|
||||
return this.list({ ...q, filter: "downloading" });
|
||||
}
|
||||
|
||||
/** 按 hash 精确查询,不受管理标签限制。查不到返回 null;下载器不可达抛错(不能当作不存在)。 */
|
||||
async findByHash(hash: string): Promise<QbTorrent | null> {
|
||||
const h = hash.toLowerCase();
|
||||
const rows = await this.list({ hashes: [h] });
|
||||
return rows.find((t) => t.hash === h || t.infohashV1 === h || t.infohashV2?.startsWith(h)) ?? null;
|
||||
}
|
||||
|
||||
/** 文件列表;空列表(磁力元数据未就绪)按 retries/intervalMs 重试(对照 get_files)。 */
|
||||
async files(hash: string, opts: { retries?: number; intervalMs?: number } = {}): Promise<QbFile[]> {
|
||||
const tries = Math.max(1, opts.retries ?? 1);
|
||||
let rows: Record<string, unknown>[] = [];
|
||||
for (let i = 0; i < tries; i++) {
|
||||
if (i > 0 && opts.intervalMs) await sleep(opts.intervalMs);
|
||||
rows = await this.json<Record<string, unknown>[]>("torrents/files", { hash: hash.toLowerCase() });
|
||||
if (rows.length) break;
|
||||
}
|
||||
return rows.map((r, i) => ({
|
||||
index: num(r.index) ?? i,
|
||||
name: String(r.name ?? ""),
|
||||
size: num(r.size) ?? 0,
|
||||
progress: num(r.progress) ?? 0,
|
||||
priority: num(r.priority) ?? 1,
|
||||
isSeed: typeof r.is_seed === "boolean" ? r.is_seed : null,
|
||||
}));
|
||||
}
|
||||
|
||||
private async pauseLike(hashes: string[], legacy: string, modern: string): Promise<void> {
|
||||
if (!hashes.length) return;
|
||||
const data = { hashes: hashes.join("|") };
|
||||
if (this.legacyPauseApi !== false) {
|
||||
try {
|
||||
await this.post(legacy, data);
|
||||
this.legacyPauseApi = true;
|
||||
return;
|
||||
} catch (e) {
|
||||
if (!(e instanceof DownloaderError && e.kind === "notfound" && this.legacyPauseApi === null)) throw e;
|
||||
this.legacyPauseApi = false;
|
||||
}
|
||||
}
|
||||
await this.post(modern, data);
|
||||
}
|
||||
|
||||
pause(hashes: string[]): Promise<void> {
|
||||
return this.pauseLike(hashes, "torrents/pause", "torrents/stop");
|
||||
}
|
||||
resume(hashes: string[]): Promise<void> {
|
||||
return this.pauseLike(hashes, "torrents/resume", "torrents/start");
|
||||
}
|
||||
|
||||
async addTags(hashes: string[], tags: string[]): Promise<void> {
|
||||
await this.post("torrents/addTags", { hashes: hashes.join("|"), tags: tags.join(",") });
|
||||
}
|
||||
async removeTags(hashes: string[], tags: string[]): Promise<void> {
|
||||
await this.post("torrents/removeTags", { hashes: hashes.join("|"), tags: tags.join(",") });
|
||||
}
|
||||
async deleteTagDefinitions(tags: string[]): Promise<void> {
|
||||
await this.post("torrents/deleteTags", { tags: tags.join(",") });
|
||||
}
|
||||
async deleteTorrentsTag(hashes: string[] | null, tags: string[]): Promise<void> {
|
||||
if (hashes?.length) await this.removeTags(hashes, tags);
|
||||
await this.deleteTagDefinitions(tags);
|
||||
}
|
||||
|
||||
async setFilePriority(hash: string, fileIds: number[], priority: 0 | 1 | 6 | 7): Promise<boolean> {
|
||||
if (!hash || !fileIds.length) return false;
|
||||
await this.post("torrents/filePrio", {
|
||||
hash: hash.toLowerCase(),
|
||||
id: fileIds.join("|"),
|
||||
priority: String(priority),
|
||||
});
|
||||
return true;
|
||||
}
|
||||
|
||||
async setForceStart(hashes: string[], enable = true): Promise<void> {
|
||||
if (!hashes.length) return;
|
||||
await this.post("torrents/setForceStart", { hashes: hashes.join("|"), value: String(enable) });
|
||||
}
|
||||
|
||||
async recheck(hashes: string[]): Promise<void> {
|
||||
if (!hashes.length) return;
|
||||
await this.post("torrents/recheck", { hashes: hashes.join("|") });
|
||||
}
|
||||
|
||||
async setLocation(hashes: string[], location: string): Promise<void> {
|
||||
if (!hashes.length || !location) return;
|
||||
await this.post("torrents/setLocation", { hashes: hashes.join("|"), location });
|
||||
}
|
||||
|
||||
async setCategory(hashes: string[], category: string): Promise<void> {
|
||||
if (!hashes.length) return;
|
||||
await this.post("torrents/setCategory", { hashes: hashes.join("|"), category });
|
||||
}
|
||||
|
||||
/** 对照 change_torrent:限速单位 KB/s → B/s;只给 seedingTime 时 ratioLimit=-2(沿用全局)。 */
|
||||
async changeTorrent(hash: string, o: TorrentLimits): Promise<void> {
|
||||
const h = hash.toLowerCase();
|
||||
if (o.uploadLimitKBps !== undefined) {
|
||||
await this.post("torrents/setUploadLimit", { hashes: h, limit: String(Math.trunc(o.uploadLimitKBps * 1024)) });
|
||||
}
|
||||
if (o.downloadLimitKBps !== undefined) {
|
||||
await this.post("torrents/setDownloadLimit", {
|
||||
hashes: h,
|
||||
limit: String(Math.trunc(o.downloadLimitKBps * 1024)),
|
||||
});
|
||||
}
|
||||
if (o.ratioLimit !== undefined || o.seedingTimeLimitMin !== undefined) {
|
||||
await this.post("torrents/setShareLimits", {
|
||||
hashes: h,
|
||||
ratioLimit: o.ratioLimit !== undefined ? String(Math.round(o.ratioLimit * 100) / 100) : "-2",
|
||||
seedingTimeLimit: String(Math.trunc(o.seedingTimeLimitMin ?? -1)),
|
||||
inactiveSeedingTimeLimit: "-1",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async preferences(): Promise<Record<string, unknown>> {
|
||||
return this.json<Record<string, unknown>>("app/preferences");
|
||||
}
|
||||
|
||||
async contentLayout(): Promise<"Original" | "Subfolder" | "NoSubfolder"> {
|
||||
const v = (await this.preferences()).torrent_content_layout;
|
||||
return v === "Subfolder" || v === "NoSubfolder" ? v : "Original";
|
||||
}
|
||||
|
||||
async transferInfo(): Promise<Record<string, unknown>> {
|
||||
return this.json<Record<string, unknown>>("transfer/info");
|
||||
}
|
||||
|
||||
async delete(hashes: string[], opts: { deleteFiles: boolean }): Promise<void> {
|
||||
if (typeof opts?.deleteFiles !== "boolean") throw new TypeError("deleteFiles must be explicit");
|
||||
if (!hashes.length) return;
|
||||
await this.post("torrents/delete", { hashes: hashes.join("|"), deleteFiles: String(opts.deleteFiles) });
|
||||
}
|
||||
|
||||
async mainData(rid = 0): Promise<QbMainData> {
|
||||
const j = await this.json<Record<string, unknown>>("sync/maindata", { rid: String(rid) });
|
||||
return {
|
||||
rid: num(j.rid) ?? 0,
|
||||
fullUpdate: j.full_update === true,
|
||||
torrents: (j.torrents as Record<string, Record<string, unknown>>) ?? {},
|
||||
torrentsRemoved: (j.torrents_removed as string[]) ?? [],
|
||||
serverState: (j.server_state as Record<string, unknown>) ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
private async pollHash(hash: string): Promise<QbTorrent | null> {
|
||||
for (let i = 0; i < this.lookup.attempts; i++) {
|
||||
if (i > 0) await sleep(this.lookup.intervalMs);
|
||||
try {
|
||||
const t = await this.findByHash(hash);
|
||||
if (t) return t;
|
||||
} catch (e) {
|
||||
if (!(e instanceof DownloaderError) || e.kind === "auth") throw e;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
private async pollTag(tag: string): Promise<QbTorrent | null> {
|
||||
for (let i = 0; i < this.lookup.attempts; i++) {
|
||||
if (i > 0) await sleep(this.lookup.intervalMs);
|
||||
try {
|
||||
const rows = await this.list({ tag });
|
||||
if (rows[0]) return rows[0];
|
||||
} catch (e) {
|
||||
if (!(e instanceof DownloaderError) || e.kind === "auth") throw e;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
private async dropProbe(tag: string, hash: string | null): Promise<void> {
|
||||
try {
|
||||
if (hash) await this.removeTags([hash], [tag]);
|
||||
await this.deleteTagDefinitions([tag]);
|
||||
} catch {
|
||||
// 残留探针标签由对账任务按前缀清理
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 幂等提交:本地算 infohash → 预查是否已存在 → add → 按 hash(或探针标签)确认。
|
||||
* add 超时/断连时不重提,先回查(REQ §8.4)。
|
||||
*/
|
||||
async submit(req: AddTorrentRequest): Promise<SubmitOutcome> {
|
||||
let hash: string | null = null;
|
||||
const src = req.source;
|
||||
if (src.kind === "file") {
|
||||
try {
|
||||
hash = parseTorrent(src.bytes).hash;
|
||||
} catch (e) {
|
||||
if (e instanceof BencodeError) return { kind: "rejected", reason: `invalid torrent: ${e.message}`, hash: null };
|
||||
throw e;
|
||||
}
|
||||
} else if (src.kind === "magnet") {
|
||||
const m = parseMagnet(src.uri);
|
||||
if (!m) return { kind: "rejected", reason: "invalid magnet uri", hash: null };
|
||||
hash = m.hash;
|
||||
} else {
|
||||
hash = parseMagnet(src.url)?.hash ?? null;
|
||||
}
|
||||
|
||||
if (hash) {
|
||||
try {
|
||||
const existing = await this.findByHash(hash);
|
||||
if (existing) return { kind: "already_exists", hash: existing.hash, existing };
|
||||
} catch (e) {
|
||||
if (e instanceof DownloaderError) return { kind: "unreachable", error: e, hash };
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
const probeTag = hash ? null : `${this.probePrefix}${Date.now().toString(36)}${randomBytes(5).toString("hex")}`;
|
||||
const tags = probeTag ? [...(req.tags ?? []), probeTag] : req.tags;
|
||||
let result: AddTorrentResult;
|
||||
try {
|
||||
result = await this.add({ ...req, ...(tags ? { tags } : {}) });
|
||||
} catch (e) {
|
||||
if (!(e instanceof DownloaderError)) throw e;
|
||||
if (e.ambiguous) {
|
||||
if (hash) {
|
||||
const t = await this.pollHash(hash).catch(() => null);
|
||||
if (t) return { kind: "added", hash: t.hash, via: "recovered_after_timeout" };
|
||||
return { kind: "unreachable", error: e, hash };
|
||||
}
|
||||
const t = await this.pollTag(probeTag!).catch(() => null);
|
||||
if (t) {
|
||||
await this.dropProbe(probeTag!, t.hash);
|
||||
return { kind: "added", hash: t.hash, via: "recovered_after_timeout" };
|
||||
}
|
||||
return { kind: "accepted_unconfirmed", hash: null, probeTag };
|
||||
}
|
||||
if (e.kind === "rejected") {
|
||||
if (hash) {
|
||||
const t = await this.findByHash(hash).catch(() => null);
|
||||
if (t) return { kind: "already_exists", hash: t.hash, existing: t };
|
||||
}
|
||||
if (probeTag) await this.dropProbe(probeTag, null);
|
||||
return { kind: "rejected", reason: e.message, hash };
|
||||
}
|
||||
return { kind: "unreachable", error: e, hash };
|
||||
}
|
||||
|
||||
if (!result.accepted) {
|
||||
// 4.x:已存在/非法链接都返回 Fails.;先查是否已存在
|
||||
if (hash) {
|
||||
const t = await this.findByHash(hash).catch(() => null);
|
||||
if (t) return { kind: "already_exists", hash: t.hash, existing: t };
|
||||
}
|
||||
if (probeTag) await this.dropProbe(probeTag, null);
|
||||
return { kind: "rejected", reason: `downloader refused: ${result.raw.slice(0, 200)}`, hash };
|
||||
}
|
||||
|
||||
const knownHash = hash ?? result.addedIds[0] ?? null;
|
||||
if (knownHash) {
|
||||
const t = await this.pollHash(knownHash).catch(() => null);
|
||||
if (probeTag) await this.dropProbe(probeTag, t?.hash ?? knownHash);
|
||||
if (t) return { kind: "added", hash: t.hash, via: hash ? "confirmed" : "added_ids" };
|
||||
return { kind: "accepted_unconfirmed", hash: knownHash, probeTag: null };
|
||||
}
|
||||
const t = await this.pollTag(probeTag!).catch(() => null);
|
||||
if (t) {
|
||||
await this.dropProbe(probeTag!, t.hash);
|
||||
return { kind: "added", hash: t.hash, via: "probe_tag" };
|
||||
}
|
||||
return { kind: "accepted_unconfirmed", hash: null, probeTag };
|
||||
}
|
||||
}
|
||||
|
||||
export function createQbClient(cfg: QbInstanceConfig): DownloaderClient & { login(): Promise<void> } {
|
||||
return new QbClient(cfg);
|
||||
}
|
||||
|
||||
/** 多实例注册表:按 instanceId 取客户端。 */
|
||||
export class DownloaderRegistry {
|
||||
private readonly clients = new Map<string, DownloaderClient>();
|
||||
constructor(configs: QbInstanceConfig[] = []) {
|
||||
for (const c of configs) this.register(c);
|
||||
}
|
||||
register(cfg: QbInstanceConfig): DownloaderClient {
|
||||
const c = new QbClient(cfg);
|
||||
this.clients.set(cfg.instanceId, c);
|
||||
return c;
|
||||
}
|
||||
get(instanceId: string): DownloaderClient | undefined {
|
||||
return this.clients.get(instanceId);
|
||||
}
|
||||
remove(instanceId: string): boolean {
|
||||
return this.clients.delete(instanceId);
|
||||
}
|
||||
list(): DownloaderClient[] {
|
||||
return [...this.clients.values()];
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user