Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

fix(downloads): select qBittorrent jobs before display limit (#7107)

Thomas69e3976297b0
diff --git a/packages/api/src/router/widgets/downloads.ts b/packages/api/src/router/widgets/downloads.ts
index b6b448a2c..0e2de7745 100644
--- a/packages/api/src/router/widgets/downloads.ts
+++ b/packages/api/src/router/widgets/downloads.ts
@@ -52,13 +52,39 @@ export const downloadsRouter = createTRPCRouter({
mcp: {
enabled: true,
description:
- "Get active download jobs and queue status from connected download clients (qBittorrent, SABnzbd, Transmission, Deluge, NZBGet). REQUIRED: integrationIds (array of download client integration IDs from integration_all). OPTIONAL: limitPerIntegration (number, default 50). For SABnzbd, includeArchivedHistory includes archived jobs when true and defaults to false; historyWindowDays is a positive whole number of days and defaults to 7. Archived history is scanned in pages of 100, up to 100 pages.",
+ "Get active download jobs and queue status from connected download clients (qBittorrent, SABnzbd, Transmission, Deluge, NZBGet). REQUIRED: integrationIds (array of download client integration IDs from integration_all). OPTIONAL: limitPerIntegration (number, default 50). For qBittorrent, optional selection applies completed/category filters and provider-compatible sorting before the display limit, scanning at most 100 pages of at most 100 torrents. Unsupported sort fields and other providers still sort the returned window locally. For SABnzbd, includeArchivedHistory includes archived jobs when true and defaults to false; historyWindowDays is a positive whole number of days and defaults to 7. Archived history is scanned in pages of 100, up to 100 pages.",
},
})
.concat(createManyWidgetIntegrationMiddleware("query", "downloads"))
.input(
z.object({
limitPerIntegration: z.number().default(50),
+ selection: z
+ .object({
+ sort: z.enum([
+ "name",
+ "progress",
+ "size",
+ "downSpeed",
+ "upSpeed",
+ "time",
+ "added",
+ "ratio",
+ "received",
+ "sent",
+ "index",
+ "type",
+ "state",
+ "category",
+ "integration",
+ ]),
+ descending: z.boolean(),
+ categoryFilter: z.array(z.string().max(1000)).max(100),
+ filterIsWhitelist: z.boolean(),
+ showCompletedTorrent: z.boolean(),
+ activeTorrentThreshold: z.number().min(0),
+ })
+ .optional(),
includeArchivedHistory: z.boolean().default(false),
historyWindowDays: z.number().int().min(1).default(7),
}),
@@ -69,6 +95,7 @@ export const downloadsRouter = createTRPCRouter({
async (integration) => {
const innerHandler = downloadClientRequestHandler.handler(integration, {
limit: input.limitPerIntegration,
+ selection: input.selection,
includeArchivedHistory: input.includeArchivedHistory,
historyWindowDays: input.historyWindowDays,
});
diff --git a/packages/integrations/index.ts b/packages/integrations/index.ts
index 3bd16e178..1d9b6e904 100644
--- a/packages/integrations/index.ts
+++ b/packages/integrations/index.ts
@@ -1 +1,3 @@
export * from "./src";
+
+export type { DownloadClientSelection } from "./src/interfaces/downloads/download-client-integration";
diff --git a/packages/integrations/src/download-client/qbittorrent/qbittorrent-integration.ts b/packages/integrations/src/download-client/qbittorrent/qbittorrent-integration.ts
index c08dd5848..1b11f4512 100644
--- a/packages/integrations/src/download-client/qbittorrent/qbittorrent-integration.ts
+++ b/packages/integrations/src/download-client/qbittorrent/qbittorrent-integration.ts
@@ -11,7 +11,10 @@ import type { IntegrationTestingInput } from "../../base/integration";
import { TestConnectionError } from "../../base/test-connection/test-connection-error";
import type { TestingResult } from "../../base/test-connection/test-connection-service";
import type { DownloadClientJobsAndStatus } from "../../interfaces/downloads/download-client-data";
-import type { IDownloadClientIntegration } from "../../interfaces/downloads/download-client-integration";
+import type {
+ DownloadClientSelection,
+ IDownloadClientIntegration,
+} from "../../interfaces/downloads/download-client-integration";
import type { DownloadClientItem } from "../../interfaces/downloads/download-client-items";
import type { DownloadClientStatus } from "../../interfaces/downloads/download-client-status";
@@ -27,10 +30,13 @@ export class QBitTorrentIntegration extends Integration implements IDownloadClie
};
}
- public async getClientJobsAndStatusAsync(input: { limit: number }): Promise<DownloadClientJobsAndStatus> {
+ public async getClientJobsAndStatusAsync(input: {
+ limit: number;
+ selection?: DownloadClientSelection;
+ }): Promise<DownloadClientJobsAndStatus> {
const type = "torrent";
const client = await this.getClientAsync();
- const torrents = await client.listTorrents({ limit: input.limit });
+ const torrents = await this.getSelectedTorrentsAsync(client, input);
const rates = torrents.reduce(
({ down, up }, { dlspeed, upspeed }) => ({ down: down + dlspeed, up: up + upspeed }),
{ down: 0, up: 0 },
@@ -61,7 +67,109 @@ export class QBitTorrentIntegration extends Integration implements IDownloadClie
category: torrent.category,
};
});
- return { status, items };
+ if (!input.selection) return { status, items };
+
+ const [transferInfo, runningTorrents, ratioItems] = await Promise.all([
+ client.request<{ dl_info_speed: number; up_info_speed: number }>("/transfer/info", "GET"),
+ client.listTorrents({ filter: "running", limit: 1 }),
+ this.getRatioItemsAsync(client, input.limit),
+ ]);
+ return {
+ items,
+ ratioItems,
+ status: {
+ paused: runningTorrents.length === 0,
+ rates: { down: transferInfo.dl_info_speed, up: transferInfo.up_info_speed },
+ types: [type],
+ },
+ };
+ }
+
+ private async getRatioItemsAsync(client: QBittorrent, limit: number) {
+ // Preserve the original unfiltered limited population without retaining full provider objects.
+ const ratioItems: NonNullable<DownloadClientJobsAndStatus["ratioItems"]> = [];
+ const seen = new Set<string>();
+ for (let page = 0; page < 100 && ratioItems.length < limit; page++) {
+ const pageSize = Math.min(limit - ratioItems.length, 100);
+ const batch = await client.listTorrents({ limit: pageSize, offset: page * 100 });
+ const previousCount = ratioItems.length;
+ for (const torrent of batch) {
+ if (seen.has(torrent.hash)) continue;
+ seen.add(torrent.hash);
+ ratioItems.push({
+ sent: torrent.uploaded,
+ size: torrent.size,
+ progress: torrent.progress,
+ category: torrent.category,
+ });
+ if (ratioItems.length >= limit) break;
+ }
+ // qBittorrent 4 wraps out-of-range offsets back to the first page.
+ if (batch.length < pageSize || ratioItems.length === previousCount) break;
+ }
+ return ratioItems;
+ }
+
+ private async getSelectedTorrentsAsync(
+ client: QBittorrent,
+ { limit, selection }: { limit: number; selection?: DownloadClientSelection },
+ ) {
+ if (!selection) return await client.listTorrents({ limit });
+
+ // Only fields with the same meaning in the provider and widget can select the remote window.
+ const sortFields: Record<string, string> = {
+ name: "name",
+ progress: "progress",
+ size: "size",
+ added: "added_on",
+ index: "priority",
+ upSpeed: "upspeed",
+ downSpeed: "dlspeed",
+ sent: "uploaded",
+ };
+ let category: string | undefined;
+ if (selection.filterIsWhitelist && selection.categoryFilter.length === 1) {
+ category = selection.categoryFilter[0];
+ }
+
+ // Bound every response, retained items, and total work even when nearly the whole queue is hidden.
+ let pageSize = Math.min(limit, 100);
+ if (
+ selection.categoryFilter.length > 0 ||
+ !selection.showCompletedTorrent ||
+ selection.activeTorrentThreshold > 0
+ ) {
+ pageSize = 100;
+ }
+ const torrents: Awaited<ReturnType<QBittorrent["listTorrents"]>> = [];
+ const seen = new Set<string>();
+ for (let page = 0; page < 100 && torrents.length < limit; page++) {
+ const previousSeenCount = seen.size;
+ const batch = await client.listTorrents({
+ limit: pageSize,
+ offset: page * pageSize,
+ sort: sortFields[selection.sort],
+ reverse: selection.descending,
+ category,
+ });
+ for (const torrent of batch) {
+ if (seen.has(torrent.hash)) continue;
+ seen.add(torrent.hash);
+ if (selection.categoryFilter.length > 0) {
+ const matches = selection.categoryFilter.includes(torrent.category);
+ if (selection.filterIsWhitelist !== matches) continue;
+ }
+ if (torrent.progress >= 1) {
+ if (!selection.showCompletedTorrent) continue;
+ if (torrent.upspeed < selection.activeTorrentThreshold * 1024) continue;
+ }
+ torrents.push(torrent);
+ if (torrents.length >= limit) break;
+ }
+ // qBittorrent 4 wraps out-of-range offsets back to the first page.
+ if (batch.length < pageSize || seen.size === previousSeenCount) break;
+ }
+ return torrents;
}
public async pauseQueueAsync() {
diff --git a/packages/integrations/src/interfaces/downloads/download-client-data.ts b/packages/integrations/src/interfaces/downloads/download-client-data.ts
index f82840dfe..26d80743f 100644
--- a/packages/integrations/src/interfaces/downloads/download-client-data.ts
+++ b/packages/integrations/src/interfaces/downloads/download-client-data.ts
@@ -4,4 +4,6 @@ import type { DownloadClientStatus } from "./download-client-status";
export interface DownloadClientJobsAndStatus {
status: DownloadClientStatus;
items: DownloadClientItem[];
+ /** Original limited accounting population, independent of display selection. */
+ ratioItems?: Pick<DownloadClientItem, "sent" | "size" | "progress" | "category">[];
}
diff --git a/packages/integrations/src/interfaces/downloads/download-client-integration.ts b/packages/integrations/src/interfaces/downloads/download-client-integration.ts
index bc43bee27..ee94669a5 100644
--- a/packages/integrations/src/interfaces/downloads/download-client-integration.ts
+++ b/packages/integrations/src/interfaces/downloads/download-client-integration.ts
@@ -1,9 +1,21 @@
import type { DownloadClientJobsAndStatus } from "./download-client-data";
import type { DownloadClientItem } from "./download-client-items";
+export interface DownloadClientSelection {
+ sort: string;
+ descending: boolean;
+ categoryFilter: string[];
+ filterIsWhitelist: boolean;
+ showCompletedTorrent: boolean;
+ activeTorrentThreshold: number;
+}
+
export interface IDownloadClientIntegration {
/** Get download client's status and list of all of it's items */
- getClientJobsAndStatusAsync(input: { limit: number }): Promise<DownloadClientJobsAndStatus>;
+ getClientJobsAndStatusAsync(input: {
+ limit: number;
+ selection?: DownloadClientSelection;
+ }): Promise<DownloadClientJobsAndStatus>;
/** Pauses the client or all of it's items */
pauseQueueAsync(): Promise<void>;
/** Pause a single item using it's ID */
diff --git a/packages/request-handler/src/downloads.ts b/packages/request-handler/src/downloads.ts
index baf83b784..0dc54bfc3 100644
--- a/packages/request-handler/src/downloads.ts
+++ b/packages/request-handler/src/downloads.ts
@@ -1,5 +1,5 @@
import type { IntegrationKindByCategory } from "@homarr/definitions";
-import type { DownloadClientJobsAndStatus } from "@homarr/integrations";
+import type { DownloadClientJobsAndStatus, DownloadClientSelection } from "@homarr/integrations";
import { createIntegrationAsync } from "@homarr/integrations/factory";
import { createIntegrationRequestHandler } from "./lib/integration-request-handler";
@@ -9,6 +9,7 @@ export const downloadClientRequestHandler = createIntegrationRequestHandler<
IntegrationKindByCategory<"downloadClient">,
{
limit: number;
+ selection?: DownloadClientSelection;
includeArchivedHistory: boolean;
historyWindowDays: number;
}
diff --git a/packages/widgets/src/downloads/component.tsx b/packages/widgets/src/downloads/component.tsx
index ade0fcdea..314f82296 100644
--- a/packages/widgets/src/downloads/component.tsx
+++ b/packages/widgets/src/downloads/component.tsx
@@ -439,7 +439,7 @@ export default function DownloadClientsWidget({
let initialTotalUp: number | undefined;
if (isTorrent) initialTotalUp = 0;
- const { totalUp, totalDown } = clientData.items
+ const { totalUp, totalDown } = (clientData.ratioItems ?? clientData.items)
.filter(({ category }) => {
if (!applyRatioFilter) return true;
return matchesCategoryFilter(category, options.categoryFilter, options.filterIsWhitelist);
diff --git a/packages/widgets/src/downloads/index.ts b/packages/widgets/src/downloads/index.ts
index 6fb9cc861..41383aa1f 100644
--- a/packages/widgets/src/downloads/index.ts
+++ b/packages/widgets/src/downloads/index.ts
@@ -28,12 +28,20 @@ export const { definition, componentLoader } = createWidgetDefinition("downloads
icon: IconDownload,
supportsAdvancedFocus: true,
queryKey: [["widget", "downloads", "getJobsAndStatuses"]],
- queryMatcher: ({ input }, scope) =>
- isRecord(input) &&
- widgetQueryInputMatches(
- { ...resolveDownloadsQueryInput(scope.integrationIds, input), integrationIds: input.integrationIds },
- resolveDownloadsQueryInput(scope.integrationIds, scope.options),
- ),
+ queryMatcher: ({ input }, scope) => {
+ if (!isRecord(input)) return false;
+ const expected = resolveDownloadsQueryInput(scope.integrationIds, scope.options);
+ return widgetQueryInputMatches(
+ {
+ ...resolveDownloadsQueryInput(scope.integrationIds, input),
+ integrationIds: input.integrationIds,
+ // Existing board snapshots can contain the query shape from before provider selection.
+ selection: expected.selection,
+ ...("selection" in input && { selection: input.selection }),
+ },
+ expected,
+ );
+ },
refetchInterval: 10,
createOptions() {
return optionsBuilder.from(
diff --git a/packages/widgets/src/downloads/query-input.ts b/packages/widgets/src/downloads/query-input.ts
index 8fc7a8397..bd25d0503 100644
--- a/packages/widgets/src/downloads/query-input.ts
+++ b/packages/widgets/src/downloads/query-input.ts
@@ -4,6 +4,16 @@ export const resolveDownloadsQueryInput = (integrationIds: readonly string[], op
({
integrationIds: [...integrationIds],
limitPerIntegration: Number(options.limitPerIntegration ?? 50),
+ selection: {
+ sort: (options.defaultSort ?? "progress") as NonNullable<
+ RouterInputs["widget"]["downloads"]["getJobsAndStatuses"]["selection"]
+ >["sort"],
+ descending: (options.descendingDefaultSort ?? false) === true,
+ categoryFilter: (options.categoryFilter ?? []) as string[],
+ filterIsWhitelist: (options.filterIsWhitelist ?? false) === true,
+ showCompletedTorrent: options.showCompletedTorrent !== false,
+ activeTorrentThreshold: Number(options.activeTorrentThreshold ?? 0),
+ },
includeArchivedHistory: (options.includeArchivedHistory ?? false) === true,
historyWindowDays: Number(options.historyWindowDays ?? 7),
}) satisfies RouterInputs["widget"]["downloads"]["getJobsAndStatuses"];