rootandClaude Opus 5.5
fa9221086b
adapters: assertSafeToDeleteData({contentPath, libraryRoots, importVerified}) rejects
paths inside/equal to/above any library root, relative or root paths, empty roots and
unverified imports; QbClient.delete({deleteFiles:true}) requires a per-hash
SafeDeleteCheck and throws DownloaderError('unsafe_delete') before sending anything.
testkit: mock qB complete(hash, {files, writeFiles}) writes random-content files under
save_path (opt-in, size-capped, traversal-safe); deleteFiles=true removes them.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
774 lines
30 KiB
TypeScript
774 lines
30 KiB
TypeScript
/**
|
|
* 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.ts";
|
|
import { assertSafeToDeleteData, type SafeDeleteCheck } from "./safe-delete.ts";
|
|
import { isDownloadComplete, mapQbState, type QbObservedState } from "./state.ts";
|
|
import { BencodeError, parseMagnet, parseTorrent } from "./torrent.ts";
|
|
|
|
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 必须显式给出。deleteFiles=true 时每个 hash 都要在 safety 里给出检查输入,
|
|
* 任一未通过 assertSafeToDeleteData 即抛 DownloaderError('unsafe_delete'),请求不会发出。
|
|
*/
|
|
delete(hashes: string[], opts: DeleteOptions): Promise<void>;
|
|
mainData(rid?: number): Promise<QbMainData>;
|
|
}
|
|
|
|
/** 删除选项:删数据必须附带逐个 hash 的安全检查输入(键为 hash,大小写不敏感) */
|
|
export type DeleteOptions =
|
|
| { deleteFiles: false }
|
|
| { deleteFiles: true; safety: Readonly<Record<string, SafeDeleteCheck>> };
|
|
|
|
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: DeleteOptions): Promise<void> {
|
|
if (typeof opts?.deleteFiles !== "boolean") throw new TypeError("deleteFiles must be explicit");
|
|
if (!hashes.length) return;
|
|
if (opts.deleteFiles) {
|
|
const safety = new Map(Object.entries(opts.safety ?? {}).map(([h, c]) => [h.toLowerCase(), c]));
|
|
for (const h of hashes) {
|
|
const check = safety.get(h.toLowerCase());
|
|
if (!check) {
|
|
throw this.err("unsafe_delete", `拒绝删除数据: ${h} 缺少安全检查输入`, "torrents/delete");
|
|
}
|
|
assertSafeToDeleteData(check, this.instanceId);
|
|
}
|
|
}
|
|
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()];
|
|
}
|
|
}
|