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,380 @@
|
||||
/**
|
||||
* TMDB v3 查询适配。
|
||||
* 迁移来源:MoviePilot app/modules/themoviedb/tmdbapi.py(e6820a8)与 tmdbv3api/tmdb.py 的请求缓存:
|
||||
* search_movies/search_tvs/search_multiis → search/searchAll/searchMulti;
|
||||
* __get_movie_detail/__get_tv_detail(alternative_titles、translations、external_ids)→ details;
|
||||
* get_tv_season_detail → season;tmdb.py request 的 @cached(maxsize/ttl、空结果短 TTL、业务失败不缓存)→ TtlLruCache;
|
||||
* match/match_multi 的匹配链见 match.ts。
|
||||
* 调整:网络/鉴权/限流错误以 TmdbError 抛出而非返回 None,调用方不得把"查询失败"当成"没有结果"。
|
||||
*/
|
||||
import { RequestLimiter, TtlLruCache } from "./cache";
|
||||
|
||||
export type TmdbErrorKind = "auth" | "network" | "timeout" | "notfound" | "rate" | "protocol";
|
||||
|
||||
export class TmdbError extends Error {
|
||||
override readonly name = "TmdbError";
|
||||
constructor(
|
||||
readonly kind: TmdbErrorKind,
|
||||
message: string,
|
||||
readonly detail: { path?: string; status?: number; retryAfterMs?: number; cause?: unknown } = {},
|
||||
) {
|
||||
super(message);
|
||||
}
|
||||
}
|
||||
|
||||
export type MediaEntityType = "movie" | "tv";
|
||||
|
||||
export interface CandidateTitle {
|
||||
text: string;
|
||||
/** BCP47,如 zh-CN;原名为原始语言;别名为 null */
|
||||
lang: string | null;
|
||||
kind: "localized" | "original" | "alias" | "translation";
|
||||
/** 别名/翻译的地区(iso_3166_1) */
|
||||
region?: string;
|
||||
}
|
||||
|
||||
export interface CandidateSeason {
|
||||
seasonNumber: number;
|
||||
episodeCount: number;
|
||||
name: string | null;
|
||||
airDate: string | null;
|
||||
}
|
||||
|
||||
/** 归一化的元数据候选(provider 无关结构,供 domain 身份匹配使用)。 */
|
||||
export interface MetadataCandidate {
|
||||
provider: "tmdb";
|
||||
entityType: MediaEntityType;
|
||||
externalId: string;
|
||||
/** 首选语言标题(配置 languages[0]) */
|
||||
title: string;
|
||||
originalTitle: string | null;
|
||||
originalLanguage: string | null;
|
||||
titles: CandidateTitle[];
|
||||
year: number | null;
|
||||
releaseDate: string | null;
|
||||
aliases: string[];
|
||||
originCountry: string[];
|
||||
popularity: number | null;
|
||||
overview: string | null;
|
||||
seasons?: CandidateSeason[];
|
||||
externalIds?: { imdb?: string; tvdb?: string };
|
||||
/** 是否已拉过详情(别名/季信息只在详情中完整) */
|
||||
detailed: boolean;
|
||||
}
|
||||
|
||||
export interface TmdbEpisode {
|
||||
seasonNumber: number;
|
||||
episodeNumber: number;
|
||||
name: string | null;
|
||||
airDate: string | null;
|
||||
}
|
||||
|
||||
export interface TmdbSeasonDetail {
|
||||
tvId: string;
|
||||
seasonNumber: number;
|
||||
name: string | null;
|
||||
airDate: string | null;
|
||||
episodes: TmdbEpisode[];
|
||||
}
|
||||
|
||||
export interface TmdbConfig {
|
||||
baseUrl?: string;
|
||||
/** v3 API key(query api_key) */
|
||||
apiKey?: string;
|
||||
/** v4 read access token(Bearer) */
|
||||
accessToken?: string;
|
||||
/** 查询语言,默认 ["zh-CN", "en-US"];第一个为首选 */
|
||||
languages?: string[];
|
||||
timeoutMs?: number;
|
||||
/** 429/5xx/网络错误的重试次数,默认 3 */
|
||||
retries?: number;
|
||||
retryBaseMs?: number;
|
||||
/** 429 Retry-After 的最大等待,默认 10s */
|
||||
maxRetryAfterMs?: number;
|
||||
maxConcurrent?: number;
|
||||
minIntervalMs?: number;
|
||||
/** 默认 max 1024、ttl 24h;空结果(搜索 0 条)用 emptyTtlMs,默认 30min(对照 MP EMPTY_RESULT_CACHE_TTL) */
|
||||
cache?: { max?: number; ttlMs?: number; emptyTtlMs?: number };
|
||||
fetch?: typeof fetch;
|
||||
now?: () => number;
|
||||
}
|
||||
|
||||
type Json = Record<string, unknown>;
|
||||
|
||||
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
|
||||
const s = (v: unknown): string | null => (typeof v === "string" && v !== "" ? v : null);
|
||||
const n = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
|
||||
const yearOf = (d: string | null) => (d && /^\d{4}/.test(d) ? Number(d.slice(0, 4)) : null);
|
||||
|
||||
export class TmdbClient {
|
||||
private readonly base: string;
|
||||
private readonly langs: string[];
|
||||
private readonly cache: TtlLruCache<unknown>;
|
||||
private readonly limiter: RequestLimiter;
|
||||
private readonly fetchImpl: typeof fetch;
|
||||
|
||||
constructor(private readonly cfg: TmdbConfig) {
|
||||
if (!cfg.apiKey && !cfg.accessToken) throw new TypeError("TMDB apiKey or accessToken required");
|
||||
this.base = (cfg.baseUrl ?? "https://api.themoviedb.org/3").replace(/\/+$/, "");
|
||||
this.langs = cfg.languages?.length ? cfg.languages : ["zh-CN", "en-US"];
|
||||
this.cache = new TtlLruCache(cfg.cache?.max ?? 1024, cfg.cache?.ttlMs ?? 24 * 3600_000, cfg.now);
|
||||
this.limiter = new RequestLimiter(cfg.maxConcurrent ?? 8, cfg.minIntervalMs ?? 0);
|
||||
this.fetchImpl = cfg.fetch ?? fetch;
|
||||
}
|
||||
|
||||
cacheStats() {
|
||||
return { size: this.cache.size, hits: this.cache.hits, misses: this.cache.misses, coalesced: this.cache.coalesced };
|
||||
}
|
||||
|
||||
private async get<T>(path: string, params: Record<string, string | undefined>): Promise<T> {
|
||||
const qs = new URLSearchParams();
|
||||
for (const k of Object.keys(params).sort()) if (params[k] !== undefined) qs.set(k, params[k]!);
|
||||
const key = `${path}?${qs}`;
|
||||
const emptyTtl = this.cfg.cache?.emptyTtlMs ?? 30 * 60_000;
|
||||
return this.cache.getOrLoad(
|
||||
key,
|
||||
() => this.limiter.run(() => this.fetchWithRetry(path, qs)),
|
||||
(v) =>
|
||||
Array.isArray((v as Json | null)?.results) && ((v as Json).results as unknown[]).length === 0
|
||||
? emptyTtl
|
||||
: undefined,
|
||||
) as Promise<T>;
|
||||
}
|
||||
|
||||
private async fetchWithRetry(path: string, qs: URLSearchParams): Promise<unknown> {
|
||||
const retries = this.cfg.retries ?? 3;
|
||||
let last: TmdbError | null = null;
|
||||
for (let i = 0; i <= retries; i++) {
|
||||
try {
|
||||
return await this.fetchOnce(path, qs);
|
||||
} catch (e) {
|
||||
if (!(e instanceof TmdbError)) throw e;
|
||||
last = e;
|
||||
if (!["rate", "network", "timeout", "protocol"].includes(e.kind) || i === retries) break;
|
||||
const ra = e.detail.retryAfterMs;
|
||||
await sleep(ra ?? (this.cfg.retryBaseMs ?? 500) * 2 ** i);
|
||||
}
|
||||
}
|
||||
throw last!;
|
||||
}
|
||||
|
||||
private async fetchOnce(path: string, qs: URLSearchParams): Promise<unknown> {
|
||||
const q = new URLSearchParams(qs);
|
||||
const headers: Record<string, string> = { accept: "application/json" };
|
||||
if (this.cfg.accessToken) headers.authorization = `Bearer ${this.cfg.accessToken}`;
|
||||
else q.set("api_key", this.cfg.apiKey!);
|
||||
let res: Response;
|
||||
try {
|
||||
res = await this.fetchImpl(`${this.base}${path}?${q}`, {
|
||||
headers,
|
||||
signal: AbortSignal.timeout(this.cfg.timeoutMs ?? 10_000),
|
||||
});
|
||||
} catch (e) {
|
||||
const name = (e as { name?: string })?.name;
|
||||
if (name === "TimeoutError" || name === "AbortError")
|
||||
throw new TmdbError("timeout", "TMDB request timed out", { path });
|
||||
throw new TmdbError("network", `TMDB request failed: ${(e as Error)?.message}`, { path, cause: e });
|
||||
}
|
||||
if (res.status === 401) {
|
||||
await res.body?.cancel();
|
||||
throw new TmdbError("auth", "TMDB rejected credentials", { path, status: 401 });
|
||||
}
|
||||
if (res.status === 404) {
|
||||
await res.body?.cancel();
|
||||
throw new TmdbError("notfound", `TMDB resource not found: ${path}`, { path, status: 404 });
|
||||
}
|
||||
if (res.status === 429) {
|
||||
await res.body?.cancel();
|
||||
const ra = Number(res.headers.get("retry-after"));
|
||||
const err = new TmdbError("rate", "TMDB rate limited", { path, status: 429 });
|
||||
if (Number.isFinite(ra) && ra >= 0) {
|
||||
err.detail.retryAfterMs = Math.min(ra * 1000, this.cfg.maxRetryAfterMs ?? 10_000);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
if (!res.ok) {
|
||||
await res.body?.cancel();
|
||||
throw new TmdbError("protocol", `TMDB HTTP ${res.status}`, { path, status: res.status });
|
||||
}
|
||||
try {
|
||||
return await res.json();
|
||||
} catch (e) {
|
||||
throw new TmdbError("protocol", "TMDB returned invalid JSON", { path, cause: e });
|
||||
}
|
||||
}
|
||||
|
||||
/** 单语言原始搜索(匹配链使用,对照 MP search.movies/tv_shows,语言取首选)。 */
|
||||
async searchRaw(type: MediaEntityType, query: string, year?: string | number): Promise<MetadataCandidate[]> {
|
||||
const lang = this.langs[0]!;
|
||||
const p = await this.get<Json>(`/search/${type}`, {
|
||||
query: query.trim(),
|
||||
language: lang,
|
||||
include_adult: "false",
|
||||
page: "1",
|
||||
[type === "movie" ? "year" : "first_air_date_year"]: year !== undefined && year !== "" ? String(year) : undefined,
|
||||
});
|
||||
return ((Array.isArray(p.results) ? p.results : []) as Json[]).map((r) => this.fromBrief(type, r, lang));
|
||||
}
|
||||
|
||||
/** /search/multi,只保留 movie/tv(对照 _project_multi_search_results)。 */
|
||||
async searchMulti(query: string): Promise<MetadataCandidate[]> {
|
||||
const lang = this.langs[0]!;
|
||||
const p = await this.get<Json>("/search/multi", {
|
||||
query: query.trim(),
|
||||
language: lang,
|
||||
include_adult: "false",
|
||||
page: "1",
|
||||
});
|
||||
return ((Array.isArray(p.results) ? p.results : []) as Json[])
|
||||
.filter((r) => r.media_type === "movie" || r.media_type === "tv")
|
||||
.map((r) => this.fromBrief(r.media_type as MediaEntityType, r, lang));
|
||||
}
|
||||
|
||||
private fromBrief(type: MediaEntityType, r: Json, lang: string): MetadataCandidate {
|
||||
const title = s(type === "movie" ? r.title : r.name) ?? "";
|
||||
const original = s(type === "movie" ? r.original_title : r.original_name);
|
||||
const date = s(type === "movie" ? r.release_date : r.first_air_date);
|
||||
const origLang = s(r.original_language);
|
||||
const titles: CandidateTitle[] = [];
|
||||
if (title) titles.push({ text: title, lang, kind: "localized" });
|
||||
if (original) titles.push({ text: original, lang: origLang, kind: "original" });
|
||||
return {
|
||||
provider: "tmdb",
|
||||
entityType: type,
|
||||
externalId: String(r.id),
|
||||
title,
|
||||
originalTitle: original,
|
||||
originalLanguage: origLang,
|
||||
titles,
|
||||
year: yearOf(date),
|
||||
releaseDate: date,
|
||||
aliases: [],
|
||||
originCountry: Array.isArray(r.origin_country) ? (r.origin_country as string[]) : [],
|
||||
popularity: n(r.popularity),
|
||||
overview: s(r.overview),
|
||||
detailed: false,
|
||||
};
|
||||
}
|
||||
|
||||
private static mergeTitle(c: MetadataCandidate, t: CandidateTitle) {
|
||||
if (!c.titles.some((x) => x.text === t.text && x.lang === t.lang && x.kind === t.kind)) c.titles.push(t);
|
||||
}
|
||||
|
||||
/** 按配置的多语言搜索并按 ID 合并;首选语言结果顺序优先。 */
|
||||
async search(query: string, opts: { type: MediaEntityType; year?: number }): Promise<MetadataCandidate[]> {
|
||||
const q = query.trim();
|
||||
if (!q) return [];
|
||||
const yearKey = opts.type === "movie" ? "year" : "first_air_date_year";
|
||||
const pages = await Promise.all(
|
||||
this.langs.map((lang) =>
|
||||
this.get<Json>(`/search/${opts.type}`, {
|
||||
query: q,
|
||||
language: lang,
|
||||
include_adult: "false",
|
||||
page: "1",
|
||||
[yearKey]: opts.year !== undefined ? String(opts.year) : undefined,
|
||||
}).then((p) => ({ lang, results: (Array.isArray(p.results) ? p.results : []) as Json[] })),
|
||||
),
|
||||
);
|
||||
const byId = new Map<string, MetadataCandidate>();
|
||||
for (const { lang, results } of pages) {
|
||||
for (const r of results) {
|
||||
const c = this.fromBrief(opts.type, r, lang);
|
||||
const prev = byId.get(c.externalId);
|
||||
if (!prev) byId.set(c.externalId, c);
|
||||
else for (const t of c.titles) TmdbClient.mergeTitle(prev, t);
|
||||
}
|
||||
}
|
||||
return [...byId.values()];
|
||||
}
|
||||
|
||||
/** 同时搜电影与剧集。 */
|
||||
async searchAll(query: string, opts: { year?: number } = {}): Promise<MetadataCandidate[]> {
|
||||
const [m, t] = await Promise.all([
|
||||
this.search(query, { type: "movie", ...opts }),
|
||||
this.search(query, { type: "tv", ...opts }),
|
||||
]);
|
||||
return [...m, ...t].sort((a, b) => (b.popularity ?? 0) - (a.popularity ?? 0));
|
||||
}
|
||||
|
||||
/** 详情:多语言标题、别名(alternative_titles)、外部 ID、季列表(剧集)。不存在抛 notfound。 */
|
||||
async details(type: MediaEntityType, id: string | number): Promise<MetadataCandidate> {
|
||||
const [first, ...rest] = await Promise.all(
|
||||
this.langs.map((lang, i) =>
|
||||
this.get<Json>(`/${type}/${id}`, {
|
||||
language: lang,
|
||||
append_to_response: i === 0 ? "alternative_titles,external_ids,translations" : undefined,
|
||||
}).then((j) => ({ lang, j })),
|
||||
),
|
||||
);
|
||||
const c = this.fromBrief(type, first!.j, first!.lang);
|
||||
for (const { lang, j } of rest) {
|
||||
const t = s(type === "movie" ? j.title : j.name);
|
||||
if (t) TmdbClient.mergeTitle(c, { text: t, lang, kind: "localized" });
|
||||
}
|
||||
const alt = first!.j.alternative_titles as Json | undefined;
|
||||
const altList = ((type === "movie" ? alt?.titles : alt?.results) ?? []) as Json[];
|
||||
const aliases = new Set<string>();
|
||||
for (const a of altList) {
|
||||
const text = s(a.title);
|
||||
if (!text) continue;
|
||||
aliases.add(text);
|
||||
const region = s(a.iso_3166_1);
|
||||
c.titles.push({ text, lang: null, kind: "alias", ...(region ? { region } : {}) });
|
||||
}
|
||||
// translations:MP __get_names 同样把各语言译名计入可匹配名称
|
||||
const trs = (((first!.j.translations as Json | undefined)?.translations ?? []) as Json[]).filter(Boolean);
|
||||
for (const tr of trs) {
|
||||
const data = tr.data as Json | undefined;
|
||||
const text = s(type === "movie" ? data?.title : data?.name);
|
||||
if (!text) continue;
|
||||
aliases.add(text);
|
||||
const l = s(tr.iso_639_1);
|
||||
const region = s(tr.iso_3166_1);
|
||||
TmdbClient.mergeTitle(c, {
|
||||
text,
|
||||
lang: l ? (region ? `${l}-${region}` : l) : null,
|
||||
kind: "translation",
|
||||
...(region ? { region } : {}),
|
||||
});
|
||||
}
|
||||
c.aliases = [...aliases];
|
||||
const ext = first!.j.external_ids as Json | undefined;
|
||||
if (ext) {
|
||||
const imdb = s(ext.imdb_id);
|
||||
const tvdb = ext.tvdb_id != null ? String(ext.tvdb_id) : null;
|
||||
c.externalIds = { ...(imdb ? { imdb } : {}), ...(tvdb ? { tvdb } : {}) };
|
||||
}
|
||||
if (type === "tv") {
|
||||
c.seasons = ((first!.j.seasons ?? []) as Json[]).map((x) => ({
|
||||
seasonNumber: n(x.season_number) ?? 0,
|
||||
episodeCount: n(x.episode_count) ?? 0,
|
||||
name: s(x.name),
|
||||
airDate: s(x.air_date),
|
||||
}));
|
||||
}
|
||||
c.detailed = true;
|
||||
return c;
|
||||
}
|
||||
|
||||
/** 季详情与集列表(首选语言)。 */
|
||||
async season(tvId: string | number, seasonNumber: number): Promise<TmdbSeasonDetail> {
|
||||
const j = await this.get<Json>(`/tv/${tvId}/season/${seasonNumber}`, { language: this.langs[0] });
|
||||
return {
|
||||
tvId: String(tvId),
|
||||
seasonNumber: n(j.season_number) ?? seasonNumber,
|
||||
name: s(j.name),
|
||||
airDate: s(j.air_date),
|
||||
episodes: ((j.episodes ?? []) as Json[]).map((e) => ({
|
||||
seasonNumber: n(e.season_number) ?? seasonNumber,
|
||||
episodeNumber: n(e.episode_number) ?? 0,
|
||||
name: s(e.name),
|
||||
airDate: s(e.air_date),
|
||||
})),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
export function createTmdbClient(cfg: TmdbConfig): TmdbClient {
|
||||
return new TmdbClient(cfg);
|
||||
}
|
||||
Reference in new issue
Block a user