Replace entire codebase with homarr-labs/homarr

packages/request-handler/eslint.config.js

@@ -0,0 +1,9 @@
+import baseConfig from "@homarr/eslint-config/base";
+
+/** @type {import('typescript-eslint').Config} */
+export default [
+  {
+    ignores: [],
+  },
+  ...baseConfig,
+];

packages/request-handler/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@homarr/request-handler",
+  "version": "0.1.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    "./*": "./src/*.ts"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf .turbo node_modules",
+    "format": "prettier --check . --ignore-path ../../.gitignore",
+    "lint": "eslint",
+    "typecheck": "tsc --noEmit"
+  },
+  "prettier": "@homarr/prettier-config",
+  "dependencies": {
+    "@extractus/feed-extractor": "7.1.7",
+    "@homarr/common": "workspace:^0.1.0",
+    "@homarr/core": "workspace:^0.1.0",
+    "@homarr/db": "workspace:^0.1.0",
+    "@homarr/definitions": "workspace:^0.1.0",
+    "@homarr/docker": "workspace:^0.1.0",
+    "@homarr/integrations": "workspace:^0.1.0",
+    "@homarr/redis": "workspace:^0.1.0",
+    "dayjs": "^1.11.19",
+    "octokit": "^5.0.5",
+    "superjson": "2.2.6",
+    "undici": "7.16.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@homarr/eslint-config": "workspace:^0.2.0",
+    "@homarr/prettier-config": "workspace:^0.1.0",
+    "@homarr/tsconfig": "workspace:^0.1.0",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3"
+  }
+}

packages/request-handler/src/calendar.ts

@@ -0,0 +1,28 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { CalendarEvent, RadarrReleaseType } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const calendarMonthRequestHandler = createCachedIntegrationRequestHandler<
+  CalendarEvent[],
+  IntegrationKindByCategory<"calendar">,
+  { year: number; month: number; releaseType: RadarrReleaseType[]; showUnmonitored: boolean }
+>({
+  async requestAsync(integration, input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    // Calendar component shows up to 6 days before and after the month, for example if 1. of january is sunday, it shows the last 6 days of december.
+    const startDate = dayjs().year(input.year).month(input.month).startOf("month").subtract(6, "days");
+    const endDate = dayjs().year(input.year).month(input.month).endOf("month").add(6, "days");
+
+    return await integrationInstance.getCalendarEventsAsync(
+      startDate.toDate(),
+      endDate.toDate(),
+      input.showUnmonitored,
+    );
+  },
+  cacheDuration: dayjs.duration(1, "minute"),
+  queryKey: "calendarMonth",
+});

packages/request-handler/src/dns-hole.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { DnsHoleSummary } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const dnsHoleRequestHandler = createCachedIntegrationRequestHandler<
+  DnsHoleSummary,
+  IntegrationKindByCategory<"dnsHole">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getSummaryAsync();
+  },
+  cacheDuration: dayjs.duration(5, "seconds"),
+  queryKey: "dnsHoleSummary",
+});

packages/request-handler/src/docker.ts

@@ -0,0 +1,115 @@
+import dayjs from "dayjs";
+import type { ContainerInfo, ContainerStats } from "dockerode";
+
+import { db, like, or } from "@homarr/db";
+import { icons } from "@homarr/db/schema";
+import type { ContainerState } from "@homarr/docker";
+import { dockerLabels, DockerSingleton } from "@homarr/docker";
+
+import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
+
+export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
+  queryKey: "dockerContainersResult",
+  widgetKind: "dockerContainers",
+  async requestAsync() {
+    return await getContainersWithStatsAsync();
+  },
+  cacheDuration: dayjs.duration(20, "seconds"),
+});
+
+const dockerInstances = DockerSingleton.getInstances();
+
+const extractImage = (container: ContainerInfo) => container.Image.split("/").at(-1)?.split(":").at(0) ?? "";
+
+async function getContainersWithStatsAsync() {
+  const containers = await Promise.all(
+    dockerInstances.map(async ({ instance, host }) => {
+      const instanceContainers = await instance.listContainers({ all: true });
+      return instanceContainers
+        .filter((container) => !(dockerLabels.hide in container.Labels))
+        .map((container) => ({ ...container, instance: host }));
+    }),
+  ).then((res) => res.flat());
+  const likeQueries = containers.map((container) => like(icons.name, `%${extractImage(container)}%`));
+
+  const dbIcons =
+    likeQueries.length > 0
+      ? await db.query.icons.findMany({
+          where: or(...likeQueries),
+        })
+      : [];
+
+  const containerStatsPromises = containers.map(async (container) => {
+    const instance = dockerInstances.find(({ host }) => host === container.instance)?.instance;
+    if (!instance) return null;
+
+    // Get stats, falling back to an empty stats object if fetch fails
+    // calculateCpuUsage and calculateMemoryUsage will return 0 for invalid/missing stats
+    const stats = await instance
+      .getContainer(container.Id)
+      .stats({ stream: false, "one-shot": true })
+      .catch(
+        () =>
+          ({
+            cpu_stats: { online_cpus: 0, cpu_usage: { total_usage: 0 }, system_cpu_usage: 0 },
+            memory_stats: { usage: 0 },
+          }) as ContainerStats,
+      );
+
+    const cpuUsage = calculateCpuUsage(stats);
+    const memoryUsage = calculateMemoryUsage(stats);
+
+    return {
+      id: container.Id,
+      name: container.Names[0]?.split("/")[1] ?? "Unknown",
+      state: container.State as ContainerState,
+      iconUrl:
+        dbIcons.find((icon) => {
+          const extractedImage = extractImage(container);
+          if (!extractedImage) return false;
+          return icon.name.toLowerCase().includes(extractedImage.toLowerCase());
+        })?.url ?? null,
+      cpuUsage,
+      memoryUsage,
+      image: container.Image,
+      ports: container.Ports,
+    };
+  });
+
+  return (await Promise.all(containerStatsPromises)).filter((container) => container !== null);
+}
+
+function calculateCpuUsage(stats: ContainerStats): number {
+  // Handle containers with missing or invalid stats (e.g., exited, dead containers)
+  if (!stats.cpu_stats.online_cpus || stats.cpu_stats.online_cpus === 0 || !stats.cpu_stats.cpu_usage.total_usage) {
+    return 0;
+  }
+
+  const numberOfCpus = stats.cpu_stats.online_cpus;
+  const usage = stats.cpu_stats.system_cpu_usage;
+  if (!usage || usage === 0) {
+    return 0;
+  }
+
+  return (stats.cpu_stats.cpu_usage.total_usage / usage) * numberOfCpus * 100;
+}
+
+function calculateMemoryUsage(stats: ContainerStats): number {
+  // Handle containers with missing or invalid stats (e.g., exited, dead containers)
+  if (!stats.memory_stats.usage) {
+    return 0;
+  }
+
+  // memory usage by default includes cache, which should not be shown as it is also not shown with docker stats command
+  // See https://docs.docker.com/reference/cli/docker/container/stats/ how it is / was calculated
+  return (
+    stats.memory_stats.usage -
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    (stats.memory_stats.stats?.cache ??
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      stats.memory_stats.stats?.total_inactive_file ??
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      stats.memory_stats.stats?.inactive_file ??
+      0)
+  );
+}

packages/request-handler/src/downloads.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import type { DownloadClientJobsAndStatus } from "@homarr/integrations";
+import { createIntegrationAsync } from "@homarr/integrations";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const downloadClientRequestHandler = createCachedIntegrationRequestHandler<
+  DownloadClientJobsAndStatus,
+  IntegrationKindByCategory<"downloadClient">,
+  { limit: number }
+>({
+  async requestAsync(integration, input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getClientJobsAndStatusAsync(input);
+  },
+  cacheDuration: dayjs.duration(5, "seconds"),
+  queryKey: "downloadClientJobStatus",
+});

packages/request-handler/src/firewall.ts

@@ -0,0 +1,64 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type {
+  FirewallCpuSummary,
+  FirewallInterfacesSummary,
+  FirewallMemorySummary,
+  FirewallVersionSummary,
+} from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const firewallCpuRequestHandler = createCachedIntegrationRequestHandler<
+  FirewallCpuSummary,
+  IntegrationKindByCategory<"firewall">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return integrationInstance.getFirewallCpuAsync();
+  },
+  cacheDuration: dayjs.duration(5, "seconds"),
+  queryKey: "firewallCpuSummary",
+});
+
+export const firewallMemoryRequestHandler = createCachedIntegrationRequestHandler<
+  FirewallMemorySummary,
+  IntegrationKindByCategory<"firewall">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getFirewallMemoryAsync();
+  },
+  cacheDuration: dayjs.duration(15, "seconds"),
+  queryKey: "firewallMemorySummary",
+});
+
+export const firewallInterfacesRequestHandler = createCachedIntegrationRequestHandler<
+  FirewallInterfacesSummary[],
+  IntegrationKindByCategory<"firewall">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getFirewallInterfacesAsync();
+  },
+  cacheDuration: dayjs.duration(30, "seconds"),
+  queryKey: "firewallInterfacesSummary",
+});
+
+export const firewallVersionRequestHandler = createCachedIntegrationRequestHandler<
+  FirewallVersionSummary,
+  IntegrationKindByCategory<"firewall">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getFirewallVersionAsync();
+  },
+  cacheDuration: dayjs.duration(1, "hour"),
+  queryKey: "firewallVersionSummary",
+});

packages/request-handler/src/health-monitoring.ts

@@ -0,0 +1,33 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { ProxmoxClusterInfo, SystemHealthMonitoring } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const systemInfoRequestHandler = createCachedIntegrationRequestHandler<
+  SystemHealthMonitoring,
+  Exclude<IntegrationKindByCategory<"healthMonitoring">, "proxmox">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getSystemInfoAsync();
+  },
+  cacheDuration: dayjs.duration(5, "seconds"),
+  queryKey: "systemInfo",
+});
+
+export const clusterInfoRequestHandler = createCachedIntegrationRequestHandler<
+  ProxmoxClusterInfo,
+  "proxmox" | "mock",
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getClusterInfoAsync();
+  },
+  cacheDuration: dayjs.duration(5, "seconds"),
+  queryKey: "clusterInfo",
+});

packages/request-handler/src/indexer-manager.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { Indexer } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const indexerManagerRequestHandler = createCachedIntegrationRequestHandler<
+  Indexer[],
+  IntegrationKindByCategory<"indexerManager">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getIndexersAsync();
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+  queryKey: "indexerManager",
+});

packages/request-handler/src/lib/cached-integration-request-handler.ts

@@ -0,0 +1,43 @@
+import type { Duration } from "dayjs/plugin/duration";
+
+import type { Modify } from "@homarr/common/types";
+import type { Integration, IntegrationSecret } from "@homarr/db/schema";
+import type { IntegrationKind } from "@homarr/definitions";
+import { createIntegrationOptionsChannel } from "@homarr/redis";
+
+import { createCachedRequestHandler } from "./cached-request-handler";
+
+type IntegrationOfKind<TKind extends IntegrationKind> = Omit<Integration, "kind"> & {
+  kind: TKind;
+  decryptedSecrets: Modify<Pick<IntegrationSecret, "kind" | "value">, { value: string }>[];
+  externalUrl: string | null;
+};
+
+interface Options<TData, TKind extends IntegrationKind, TInput extends Record<string, unknown>> {
+  // Unique key for this request handler
+  queryKey: string;
+  requestAsync: (integration: IntegrationOfKind<TKind>, input: TInput) => Promise<TData>;
+  cacheDuration: Duration;
+}
+
+export const createCachedIntegrationRequestHandler = <
+  TData,
+  TKind extends IntegrationKind,
+  TInput extends Record<string, unknown>,
+>(
+  options: Options<TData, TKind, TInput>,
+) => {
+  return {
+    handler: (integration: IntegrationOfKind<TKind>, itemOptions: TInput) =>
+      createCachedRequestHandler({
+        queryKey: options.queryKey,
+        requestAsync: async (input: { options: TInput; integration: IntegrationOfKind<TKind> }) => {
+          return await options.requestAsync(input.integration, input.options);
+        },
+        cacheDuration: options.cacheDuration,
+        createRedisChannel(input, options) {
+          return createIntegrationOptionsChannel<TData>(input.integration.id, options.queryKey, input.options);
+        },
+      }).handler({ options: itemOptions, integration }),
+  };
+};

packages/request-handler/src/lib/cached-request-handler.ts

@@ -0,0 +1,82 @@
+import dayjs from "dayjs";
+import type { Duration } from "dayjs/plugin/duration";
+
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import type { createChannelWithLatestAndEvents } from "@homarr/redis";
+
+const logger = createLogger({ module: "cachedRequestHandler" });
+
+interface Options<TData, TInput extends Record<string, unknown>> {
+  // Unique key for this request handler
+  queryKey: string;
+  requestAsync: (input: TInput) => Promise<TData>;
+  createRedisChannel: (
+    input: TInput,
+    options: Options<TData, TInput>,
+  ) => ReturnType<typeof createChannelWithLatestAndEvents<TData>>;
+  cacheDuration: Duration;
+}
+
+export const createCachedRequestHandler = <TData, TInput extends Record<string, unknown>>(
+  options: Options<TData, TInput>,
+) => {
+  return {
+    handler: (input: TInput) => {
+      const channel = options.createRedisChannel(input, options);
+
+      return {
+        async getCachedOrUpdatedDataAsync({ forceUpdate = false }) {
+          const requestNewDataAsync = async () => {
+            const data = await options.requestAsync(input);
+            await channel.publishAndUpdateLastStateAsync(data);
+            return {
+              data,
+              timestamp: new Date(),
+            };
+          };
+
+          if (forceUpdate) {
+            logger.debug("Cached request handler forced update", {
+              channel: channel.name,
+              queryKey: options.queryKey,
+            });
+            return await requestNewDataAsync();
+          }
+
+          const channelData = await channel.getAsync();
+
+          const shouldRequestNewData =
+            !channelData ||
+            dayjs().diff(channelData.timestamp, "milliseconds") > options.cacheDuration.asMilliseconds();
+
+          if (shouldRequestNewData) {
+            logger.debug("Cached request handler cache miss", {
+              channel: channel.name,
+              queryKey: options.queryKey,
+              reason: !channelData ? "no data" : "cache expired",
+            });
+            return await requestNewDataAsync();
+          }
+
+          logger.debug("Cached request handler cache hit", {
+            channel: channel.name,
+            queryKey: options.queryKey,
+            expiresAt: dayjs(channelData.timestamp).add(options.cacheDuration).toISOString(),
+          });
+
+          return channelData;
+        },
+        async invalidateAsync() {
+          logger.debug("Cached request handler invalidating cache", {
+            channel: channel.name,
+            queryKey: options.queryKey,
+          });
+          await this.getCachedOrUpdatedDataAsync({ forceUpdate: true });
+        },
+        subscribe(callback: (data: TData) => void) {
+          return channel.subscribe(callback);
+        },
+      };
+    },
+  };
+};

packages/request-handler/src/lib/cached-request-integration-job-handler.ts

@@ -0,0 +1,115 @@
+import SuperJSON from "superjson";
+
+import { hashObjectBase64, Stopwatch } from "@homarr/common";
+import { decryptSecret } from "@homarr/common/server";
+import type { MaybeArray } from "@homarr/common/types";
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
+import { db } from "@homarr/db";
+import { getItemsWithIntegrationsAsync, getServerSettingsAsync } from "@homarr/db/queries";
+import type { WidgetKind } from "@homarr/definitions";
+
+// This imports are done that way to avoid circular dependencies.
+import type { inferSupportedIntegrationsStrict } from "../../../widgets/src";
+import { reduceWidgetOptionsWithDefaultValues } from "../../../widgets/src";
+import type { WidgetComponentProps } from "../../../widgets/src/definition";
+import type { createCachedIntegrationRequestHandler } from "./cached-integration-request-handler";
+
+const logger = createLogger({ module: "cachedRequestIntegrationJobHandler" });
+
+export const createRequestIntegrationJobHandler = <
+  TWidgetKind extends WidgetKind,
+  TIntegrationKind extends inferSupportedIntegrationsStrict<TWidgetKind>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  THandler extends ReturnType<typeof createCachedIntegrationRequestHandler<any, TIntegrationKind, any>>["handler"],
+>(
+  handler: THandler,
+  {
+    widgetKinds,
+    getInput,
+  }: {
+    widgetKinds: TWidgetKind[];
+    getInput: {
+      [key in TWidgetKind]: (options: WidgetComponentProps<key>["options"]) => MaybeArray<Parameters<THandler>[1]>;
+    };
+  },
+) => {
+  return async () => {
+    const serverSettings = await getServerSettingsAsync(db);
+    const itemsForIntegration = await getItemsWithIntegrationsAsync(db, {
+      kinds: widgetKinds,
+    });
+
+    logger.debug("Found items for integration", {
+      widgetKinds: widgetKinds.join(","),
+      count: itemsForIntegration.length,
+    });
+
+    const distinctIntegrations: {
+      integrationId: string;
+      inputHash: string;
+      integration: (typeof itemsForIntegration)[number]["integrations"][number]["integration"];
+      input: Parameters<THandler>[1];
+    }[] = [];
+
+    for (const itemForIntegration of itemsForIntegration) {
+      const oneOrMultipleInputs = getInput[itemForIntegration.kind](
+        reduceWidgetOptionsWithDefaultValues(
+          itemForIntegration.kind,
+          {
+            enableStatusByDefault: serverSettings.board.enableStatusByDefault,
+            forceDisableStatus: serverSettings.board.forceDisableStatus,
+          },
+          SuperJSON.parse<Record<string, unknown>>(itemForIntegration.options),
+        ) as never,
+      );
+      for (const { integration } of itemForIntegration.integrations) {
+        const inputArray = Array.isArray(oneOrMultipleInputs) ? oneOrMultipleInputs : [oneOrMultipleInputs];
+
+        for (const input of inputArray) {
+          const inputHash = hashObjectBase64(input);
+          if (
+            distinctIntegrations.some(
+              (distinctIntegration) =>
+                distinctIntegration.integrationId === integration.id && distinctIntegration.inputHash === inputHash,
+            )
+          ) {
+            continue;
+          }
+
+          distinctIntegrations.push({ integrationId: integration.id, inputHash, integration, input });
+        }
+      }
+    }
+
+    for (const { integrationId, integration, input, inputHash } of distinctIntegrations) {
+      try {
+        const decryptedSecrets = integration.secrets.map((secret) => ({
+          ...secret,
+          value: decryptSecret(secret.value),
+        }));
+
+        const innerHandler = handler(
+          {
+            ...integration,
+            kind: integration.kind as TIntegrationKind,
+            decryptedSecrets,
+            externalUrl: integration.app?.href ?? null,
+          },
+          input,
+        );
+        const stopWatch = new Stopwatch();
+        await innerHandler.getCachedOrUpdatedDataAsync({ forceUpdate: true });
+        logger.debug("Ran integration job", {
+          integration: integrationId,
+          inputHash,
+          elapsed: stopWatch.getElapsedInHumanWords(),
+        });
+      } catch (error) {
+        logger.error(
+          new ErrorWithMetadata("Failed to run integration job", { integrationId, inputHash }, { cause: error }),
+        );
+      }
+    }
+  };
+};

packages/request-handler/src/lib/cached-widget-request-handler.ts

@@ -0,0 +1,36 @@
+import type { Duration } from "dayjs/plugin/duration";
+
+import type { WidgetKind } from "@homarr/definitions";
+import { createWidgetOptionsChannel } from "@homarr/redis";
+
+import { createCachedRequestHandler } from "./cached-request-handler";
+
+interface Options<TData, TKind extends WidgetKind, TInput extends Record<string, unknown>> {
+  // Unique key for this request handler
+  queryKey: string;
+  requestAsync: (input: TInput) => Promise<TData>;
+  cacheDuration: Duration;
+  widgetKind: TKind;
+}
+
+export const createCachedWidgetRequestHandler = <
+  TData,
+  TKind extends WidgetKind,
+  TInput extends Record<string, unknown>,
+>(
+  requestHandlerOptions: Options<TData, TKind, TInput>,
+) => {
+  return {
+    handler: (widgetOptions: TInput) =>
+      createCachedRequestHandler({
+        queryKey: requestHandlerOptions.queryKey,
+        requestAsync: async (input: TInput) => {
+          return await requestHandlerOptions.requestAsync(input);
+        },
+        cacheDuration: requestHandlerOptions.cacheDuration,
+        createRedisChannel(input, options) {
+          return createWidgetOptionsChannel<TData>(requestHandlerOptions.widgetKind, options.queryKey, input);
+        },
+      }).handler(widgetOptions),
+  };
+};

packages/request-handler/src/media-release.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { MediaRelease } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const mediaReleaseRequestHandler = createCachedIntegrationRequestHandler<
+  MediaRelease[],
+  IntegrationKindByCategory<"mediaRelease">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getMediaReleasesAsync();
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+  queryKey: "mediaReleases",
+});

packages/request-handler/src/media-request-list.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { MediaRequest } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const mediaRequestListRequestHandler = createCachedIntegrationRequestHandler<
+  MediaRequest[],
+  IntegrationKindByCategory<"mediaRequest">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getRequestsAsync();
+  },
+  cacheDuration: dayjs.duration(1, "minute"),
+  queryKey: "mediaRequestList",
+});

packages/request-handler/src/media-request-stats.ts

@@ -0,0 +1,23 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { MediaRequestStats } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const mediaRequestStatsRequestHandler = createCachedIntegrationRequestHandler<
+  MediaRequestStats,
+  IntegrationKindByCategory<"mediaRequest">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return {
+      stats: await integrationInstance.getStatsAsync(),
+      users: await integrationInstance.getUsersAsync(),
+    };
+  },
+  cacheDuration: dayjs.duration(1, "minute"),
+  queryKey: "mediaRequestStats",
+});

packages/request-handler/src/media-server.ts

@@ -0,0 +1,22 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import type { StreamSession } from "@homarr/integrations";
+import { createIntegrationAsync } from "@homarr/integrations";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const mediaServerRequestHandler = createCachedIntegrationRequestHandler<
+  StreamSession[],
+  IntegrationKindByCategory<"mediaService">,
+  {
+    showOnlyPlaying: boolean;
+  }
+>({
+  async requestAsync(integration, input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getCurrentSessionsAsync({ showOnlyPlaying: input.showOnlyPlaying });
+  },
+  cacheDuration: dayjs.duration(5, "seconds"),
+  queryKey: "mediaServerSessions",
+});

packages/request-handler/src/media-transcoding.ts

@@ -0,0 +1,30 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { TdarrQueue, TdarrStatistics, TdarrWorker } from "@homarr/integrations";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const mediaTranscodingRequestHandler = createCachedIntegrationRequestHandler<
+  MediaTranscoding,
+  IntegrationKindByCategory<"mediaTranscoding">,
+  { pageOffset: number; pageSize: number }
+>({
+  queryKey: "mediaTranscoding",
+  cacheDuration: dayjs.duration(5, "minutes"),
+  async requestAsync(integration, input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return {
+      queue: await integrationInstance.getQueueAsync(input.pageOffset, input.pageSize),
+      workers: await integrationInstance.getWorkersAsync(),
+      statistics: await integrationInstance.getStatisticsAsync(),
+    };
+  },
+});
+
+export interface MediaTranscoding {
+  queue: TdarrQueue;
+  workers: TdarrWorker[];
+  statistics: TdarrStatistics;
+}

packages/request-handler/src/minecraft-server-status.ts

@@ -0,0 +1,38 @@
+import dayjs from "dayjs";
+import { z } from "zod/v4";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
+
+import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
+
+export const minecraftServerStatusRequestHandler = createCachedWidgetRequestHandler({
+  queryKey: "minecraftServerStatusApiResult",
+  widgetKind: "minecraftServerStatus",
+  async requestAsync(input: { domain: string; isBedrockServer: boolean }) {
+    const path = `${input.isBedrockServer ? "/bedrock" : ""}/3/${input.domain}`;
+
+    const response = await withTimeoutAsync(async (signal) =>
+      fetchWithTrustedCertificatesAsync(`https://api.mcsrvstat.us${path}`, { signal }),
+    );
+    return responseSchema.parse(await response.json());
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+});
+
+const responseSchema = z
+  .object({
+    online: z.literal(false),
+  })
+  .or(
+    z.object({
+      online: z.literal(true),
+      players: z.object({
+        online: z.number(),
+        max: z.number(),
+      }),
+      icon: z.string().optional(),
+    }),
+  );
+
+export type MinecraftServerStatus = z.infer<typeof responseSchema>;

packages/request-handler/src/network-controller.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+import type { NetworkControllerSummary } from "@homarr/integrations/types";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const networkControllerRequestHandler = createCachedIntegrationRequestHandler<
+  NetworkControllerSummary,
+  IntegrationKindByCategory<"networkController">,
+  Record<string, never>
+>({
+  async requestAsync(integration, _input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getNetworkSummaryAsync();
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+  queryKey: "networkControllerSummary",
+});

packages/request-handler/src/notifications.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import type { Notification } from "@homarr/integrations";
+import { createIntegrationAsync } from "@homarr/integrations";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const notificationsRequestHandler = createCachedIntegrationRequestHandler<
+  Notification[],
+  IntegrationKindByCategory<"notifications">,
+  Record<string, never>
+>({
+  async requestAsync(integration) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getNotificationsAsync();
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+  queryKey: "notificationsJobStatus",
+});

packages/request-handler/src/releases.ts

@@ -0,0 +1,20 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import type { ReleaseResponse, ReleasesRepository } from "@homarr/integrations";
+import { createIntegrationAsync } from "@homarr/integrations";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const releasesRequestHandler = createCachedIntegrationRequestHandler<
+  ReleaseResponse,
+  IntegrationKindByCategory<"releasesProvider">,
+  ReleasesRepository
+>({
+  requestAsync: async (integration, input) => {
+    const instance = await createIntegrationAsync(integration);
+    return instance.getLatestMatchingReleaseAsync(input.identifier, input.versionRegex);
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+  queryKey: "repositoriesReleases",
+});

packages/request-handler/src/rss-feeds.ts

@@ -0,0 +1,129 @@
+import type { FeedData, FeedEntry } from "@extractus/feed-extractor";
+import { extract } from "@extractus/feed-extractor";
+import dayjs from "dayjs";
+import { z } from "zod/v4";
+
+import type { Modify } from "@homarr/common/types";
+import { createLogger } from "@homarr/core/infrastructure/logs";
+
+import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
+
+const logger = createLogger({ module: "rssFeedsRequestHandler" });
+
+export const rssFeedsRequestHandler = createCachedWidgetRequestHandler({
+  queryKey: "rssFeedList",
+  widgetKind: "rssFeed",
+  async requestAsync(input: { url: string; count: number }) {
+    const result = (await extract(input.url, {
+      getExtraEntryFields: (feedEntry) => {
+        const media = attemptGetImageFromEntry(input.url, feedEntry);
+        if (!media) {
+          return {};
+        }
+        return {
+          enclosure: media,
+        };
+      },
+    })) as ExtendedFeedData;
+
+    return {
+      ...result,
+      entries: result.entries?.slice(0, input.count) ?? [],
+    };
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+});
+
+const attemptGetImageFromEntry = (feedUrl: string, entry: object) => {
+  const media = getFirstMediaProperty(entry);
+  if (media !== null) {
+    return media;
+  }
+  return getImageFromStringAsFallback(feedUrl, JSON.stringify(entry));
+};
+
+const getImageFromStringAsFallback = (feedUrl: string, content: string) => {
+  const regex = /https?:\/\/\S+?\.(jpg|jpeg|png|gif|bmp|svg|webp|tiff)/i;
+  const result = regex.exec(content);
+
+  if (result == null) {
+    return null;
+  }
+
+  console.debug(
+    `Falling back to regex image search for '${feedUrl}'. Found ${result.length} matches in content: ${content}`,
+  );
+  return result[0];
+};
+
+const mediaProperties = [
+  {
+    path: ["enclosure", "@_url"],
+  },
+  {
+    path: ["media:content", "@_url"],
+  },
+];
+
+/**
+ * The RSS and Atom standards are poorly adhered to in most of the web.
+ * We want to show pretty background images on the posts and therefore need to extract
+ * the enclosure (aka. media images). This function uses the dynamic properties defined above
+ * to search through the possible paths and detect valid image URLs.
+ * @param feedObject The object to scan for.
+ * @returns the value of the first path that is found within the object
+ */
+const getFirstMediaProperty = (feedObject: object) => {
+  for (const mediaProperty of mediaProperties) {
+    let propertyIndex = 0;
+    let objectAtPath: object = feedObject;
+    while (propertyIndex < mediaProperty.path.length) {
+      const key = mediaProperty.path[propertyIndex];
+      if (key === undefined) {
+        break;
+      }
+      const propertyEntries = Object.entries(objectAtPath);
+      const propertyEntry = propertyEntries.find(([entryKey]) => entryKey === key);
+      if (!propertyEntry) {
+        break;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const [_, propertyEntryValue] = propertyEntry;
+      objectAtPath = propertyEntryValue as object;
+      propertyIndex++;
+    }
+
+    const validationResult = z.string().url().safeParse(objectAtPath);
+    if (!validationResult.success) {
+      continue;
+    }
+
+    logger.debug(`Found an image in the feed entry: ${validationResult.data}`);
+    return validationResult.data;
+  }
+  return null;
+};
+
+/**
+ * We extend the feed with custom properties.
+ * This interface adds properties on top of the default ones.
+ */
+interface ExtendedFeedEntry extends FeedEntry {
+  enclosure?: string;
+}
+
+/**
+ * We extend the feed with custom properties.
+ * This interface omits the default entries with our custom definition.
+ */
+type ExtendedFeedData = Modify<
+  FeedData,
+  {
+    entries?: ExtendedFeedEntry[];
+  }
+>;
+
+export interface RssFeed {
+  feedUrl: string;
+  feed: ExtendedFeedData;
+}

packages/request-handler/src/smart-home-entity-state.ts

@@ -0,0 +1,25 @@
+import dayjs from "dayjs";
+
+import type { IntegrationKindByCategory } from "@homarr/definitions";
+import { createIntegrationAsync } from "@homarr/integrations";
+
+import { createCachedIntegrationRequestHandler } from "./lib/cached-integration-request-handler";
+
+export const smartHomeEntityStateRequestHandler = createCachedIntegrationRequestHandler<
+  string,
+  IntegrationKindByCategory<"smartHomeServer">,
+  { entityId: string }
+>({
+  async requestAsync(integration, input) {
+    const integrationInstance = await createIntegrationAsync(integration);
+    const result = await integrationInstance.getEntityStateAsync(input.entityId);
+
+    if (!result.success) {
+      throw new Error(`Unable to fetch data from Home Assistant error='${result.error as string}'`);
+    }
+
+    return result.data.state;
+  },
+  cacheDuration: dayjs.duration(1, "minute"),
+  queryKey: "smartHome-entityState",
+});

packages/request-handler/src/stock-price.ts

@@ -0,0 +1,75 @@
+import dayjs from "dayjs";
+import { z } from "zod/v4";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
+
+import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
+
+export const fetchStockPriceHandler = createCachedWidgetRequestHandler({
+  queryKey: "fetchStockPriceResult",
+  widgetKind: "stockPrice",
+  async requestAsync(input: { stock: string; timeRange: string; timeInterval: string }) {
+    const response = await withTimeoutAsync(async (signal) => {
+      return await fetchWithTrustedCertificatesAsync(
+        `https://query1.finance.yahoo.com/v8/finance/chart/${input.stock}?range=${input.timeRange}&interval=${input.timeInterval}`,
+        { signal },
+      );
+    });
+    const data = dataSchema.parse(await response.json());
+
+    if ("error" in data) {
+      throw new Error(data.error.description);
+    }
+    if (data.chart.result.length !== 1) {
+      throw new Error("Received multiple results");
+    }
+    const firstResult = data.chart.result[0];
+    if (!firstResult) {
+      throw new Error("Received invalid data");
+    }
+
+    const priceHistory =
+      firstResult.indicators.quote[0]?.close.filter(
+        // Filter out null values from price arrays (Yahoo Finance returns null for missing data points)
+        (value) => value !== null && value !== undefined,
+      ) ?? [];
+
+    return {
+      priceHistory,
+      previousClose: firstResult.meta.previousClose ?? priceHistory[0] ?? 1,
+      symbol: firstResult.meta.symbol,
+      shortName: firstResult.meta.shortName,
+    };
+  },
+  cacheDuration: dayjs.duration(5, "minutes"),
+});
+
+const dataSchema = z
+  .object({
+    error: z.object({
+      description: z.string(),
+    }),
+  })
+  .or(
+    z.object({
+      chart: z.object({
+        result: z.array(
+          z.object({
+            indicators: z.object({
+              quote: z.array(
+                z.object({
+                  close: z.array(z.number().nullish()),
+                }),
+              ),
+            }),
+            meta: z.object({
+              symbol: z.string(),
+              shortName: z.string(),
+              previousClose: z.number().optional(),
+            }),
+          }),
+        ),
+      }),
+    }),
+  );

packages/request-handler/src/update-checker.ts

@@ -0,0 +1,73 @@
+import dayjs from "dayjs";
+import { Octokit } from "octokit";
+import { compareSemVer, isValidSemVer } from "semver-parser";
+
+import { env } from "@homarr/common/env";
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+import { createLogger } from "@homarr/core/infrastructure/logs";
+import { createChannelWithLatestAndEvents } from "@homarr/redis";
+import { createCachedRequestHandler } from "@homarr/request-handler/lib/cached-request-handler";
+
+import packageJson from "../../../package.json";
+
+const logger = createLogger({ module: "updateCheckerRequestHandler" });
+
+export const updateCheckerRequestHandler = createCachedRequestHandler({
+  queryKey: "homarr-update-checker",
+  cacheDuration: dayjs.duration(1, "hour"),
+  async requestAsync(_) {
+    if (env.NO_EXTERNAL_CONNECTION)
+      return {
+        availableUpdates: [],
+      };
+
+    const octokit = new Octokit({
+      request: {
+        fetch: fetchWithTrustedCertificatesAsync,
+      },
+    });
+    const releases = await octokit.rest.repos.listReleases({
+      owner: "homarr-labs",
+      repo: "homarr",
+    });
+
+    const currentVersion = (packageJson as { version: string }).version;
+    const availableReleases = [];
+
+    for (const release of releases.data) {
+      if (!isValidSemVer(release.tag_name)) {
+        logger.warn("Unable to parse semantic tag. Update check might not work.", { tagName: release.tag_name });
+        continue;
+      }
+
+      availableReleases.push(release);
+    }
+
+    const availableNewerReleases = availableReleases
+      .filter((release) => compareSemVer(release.tag_name, currentVersion) > 0)
+      .sort((releaseA, releaseB) => compareSemVer(releaseB.tag_name, releaseA.tag_name));
+    if (availableNewerReleases.length > 0) {
+      logger.info(
+        "Update checker found a new available version",
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        { version: availableReleases[0]!.tag_name, currentVersion },
+      );
+    } else {
+      logger.debug("Update checker did not find any available updates", { currentVersion });
+    }
+
+    return {
+      availableUpdates: availableNewerReleases.map((release) => ({
+        name: release.name,
+        contentHtml: release.body_html,
+        url: release.html_url,
+        tagName: release.tag_name,
+      })),
+    };
+  },
+  createRedisChannel() {
+    return createChannelWithLatestAndEvents<{
+      availableUpdates: { name: string | null; contentHtml?: string; url: string; tagName: string }[];
+    }>("homarr:update");
+  },
+});

packages/request-handler/src/weather.ts

@@ -0,0 +1,74 @@
+import dayjs from "dayjs";
+import { z } from "zod";
+
+import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
+import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
+
+import { createCachedWidgetRequestHandler } from "./lib/cached-widget-request-handler";
+
+export const weatherRequestHandler = createCachedWidgetRequestHandler({
+  queryKey: "weatherAtLocation",
+  widgetKind: "weather",
+  async requestAsync(input: { latitude: number; longitude: number }) {
+    const res = await withTimeoutAsync(async (signal) => {
+      return await fetchWithTrustedCertificatesAsync(
+        `https://api.open-meteo.com/v1/forecast?latitude=${input.latitude}&longitude=${input.longitude}&daily=weathercode,temperature_2m_max,temperature_2m_min,sunrise,sunset,wind_speed_10m_max,wind_gusts_10m_max&current_weather=true&timezone=auto`,
+        { signal },
+      );
+    });
+    const json: unknown = await res.json();
+    const weather = await atLocationOutput.parseAsync(json);
+    return {
+      current: weather.current_weather,
+      daily: weather.daily.time.map((value, index) => {
+        return {
+          time: value,
+          weatherCode: weather.daily.weathercode[index] ?? 404,
+          maxTemp: weather.daily.temperature_2m_max[index],
+          minTemp: weather.daily.temperature_2m_min[index],
+          sunrise: weather.daily.sunrise[index],
+          sunset: weather.daily.sunset[index],
+          maxWindSpeed: weather.daily.wind_speed_10m_max[index],
+          maxWindGusts: weather.daily.wind_gusts_10m_max[index],
+        };
+      }),
+    } satisfies Weather;
+  },
+  cacheDuration: dayjs.duration(1, "minute"),
+});
+
+const atLocationOutput = z.object({
+  current_weather: z.object({
+    weathercode: z.number(),
+    temperature: z.number(),
+    windspeed: z.number(),
+  }),
+  daily: z.object({
+    time: z.array(z.string()),
+    weathercode: z.array(z.number()),
+    temperature_2m_max: z.array(z.number()),
+    temperature_2m_min: z.array(z.number()),
+    sunrise: z.array(z.string()),
+    sunset: z.array(z.string()),
+    wind_speed_10m_max: z.array(z.number()),
+    wind_gusts_10m_max: z.array(z.number()),
+  }),
+});
+
+export interface Weather {
+  current: {
+    weathercode: number;
+    temperature: number;
+    windspeed: number;
+  };
+  daily: {
+    time: string;
+    weatherCode: number;
+    maxTemp: number | undefined;
+    minTemp: number | undefined;
+    sunrise: string | undefined;
+    sunset: string | undefined;
+    maxWindSpeed: number | undefined;
+    maxWindGusts: number | undefined;
+  }[];
+}

packages/request-handler/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@homarr/tsconfig/base.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json"
+  },
+  "include": ["*.ts", "src"],
+  "exclude": ["node_modules"]
+}