fix: harden widget request caching

packages/request-handler/src/air-quality.ts

@@ -5,7 +5,6 @@ import { z } from "zod";
 
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
-import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
 
 import { createWidgetRequestHandler } from "./lib/widget-request-handler";
 
@@ -44,11 +43,12 @@ const requestedVariables = [
 ] as const;
 
 export const airQualityRequestHandler = createWidgetRequestHandler({
-  cacheNamespace: "air-quality",
+  // Coordinates are a public, continuous key space. Keep this cache process-local and bounded.
   cacheTtlMs: 15 * 60 * 1000,
   fallbackToStaleOnError: true,
   staleIfErrorTtlMs: 24 * 60 * 60 * 1000,
-  async requestAsync(input: { latitude: number; longitude: number }) {
+  requestTimeoutMs: 10_000,
+  async requestAsync(input: { latitude: number; longitude: number }, signal: AbortSignal) {
     const url = new URL("https://air-quality-api.open-meteo.com/v1/air-quality");
     url.searchParams.set("latitude", input.latitude.toString());
     url.searchParams.set("longitude", input.longitude.toString());
@@ -57,9 +57,7 @@ export const airQualityRequestHandler = createWidgetRequestHandler({
     url.searchParams.set("forecast_days", FORECAST_DAYS.toString());
     url.searchParams.set("timezone", "auto");
 
-    const response = await withTimeoutAsync(async (signal) => {
-      return await fetchWithTrustedCertificatesAsync(url.toString(), { signal });
-    });
+    const response = await fetchWithTrustedCertificatesAsync(url.toString(), { signal });
     if (!response.ok) throw new ResponseError(response);
 
     const json: unknown = await response.json();

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

@@ -1,26 +1,63 @@
+import { createKeyedFingerprint } from "@homarr/common/server";
 import type { Modify } from "@homarr/common/types";
 import type { Integration, IntegrationSecret } from "@homarr/db/schema";
 import type { IntegrationKind } from "@homarr/definitions";
 import { invalidateIntegrationResponseCacheAsync } from "@homarr/redis";
 
-import { createIntegrationSharedCacheAsync, hashIntegrationCacheOptions } from "./shared-cache";
+import { createIntegrationSharedCacheAsync, hashSharedCacheInput } from "./shared-cache";
 import { createRequestHandler } from "./request-handler";
 import type { SharedCacheAdapter } from "./request-handler";
 
 type IntegrationOfKind<TKind extends IntegrationKind> = Omit<Integration, "kind"> & {
   kind: TKind;
-  decryptedSecrets: Modify<Pick<IntegrationSecret, "kind" | "value">, { value: string }>[];
+  decryptedSecrets: Modify<
+    Pick<IntegrationSecret, "kind" | "value"> & Partial<Pick<IntegrationSecret, "updatedAt">>,
+    { value: string }
+  >[];
   externalUrl: string | null;
 };
 
 interface Options<TData, TKind extends IntegrationKind, TInput extends Record<string, unknown>> {
-  requestAsync: (integration: IntegrationOfKind<TKind>, input: TInput) => Promise<TData>;
+  requestAsync: (integration: IntegrationOfKind<TKind>, input: TInput, signal: AbortSignal) => Promise<TData>;
   cacheTtlMs?: number;
   fallbackToStaleOnError?: boolean;
   staleIfErrorTtlMs?: number;
+  requestTimeoutMs?: number;
   cacheNamespace?: string;
+  cacheVersion?: string;
 }
 
+const getIntegrationCacheIdentity = <TKind extends IntegrationKind, TInput extends Record<string, unknown>>({
+  integration,
+  options,
+}: {
+  integration: IntegrationOfKind<TKind>;
+  options: TInput;
+}) => {
+  const secretRevisions = integration.decryptedSecrets
+    .map((secret) => ({
+      kind: secret.kind,
+      fingerprint: createKeyedFingerprint(JSON.stringify([secret.kind, secret.value])),
+      updatedAt: secret.updatedAt?.toISOString(),
+    }))
+    .toSorted((left, right) => {
+      const kindComparison = left.kind.localeCompare(right.kind);
+      if (kindComparison !== 0) return kindComparison;
+      return left.fingerprint.localeCompare(right.fingerprint);
+    });
+
+  return hashSharedCacheInput({
+    integration: {
+      id: integration.id,
+      kind: integration.kind,
+      url: integration.url,
+      externalUrl: integration.externalUrl,
+      secretRevisions,
+    },
+    options,
+  });
+};
+
 export const createIntegrationRequestHandler = <
   TData,
   TKind extends IntegrationKind,
@@ -30,24 +67,29 @@ export const createIntegrationRequestHandler = <
 ) => {
   const cacheNamespace = options.cacheNamespace;
   let getSharedCacheAsync:
-    | ((input: { integration: IntegrationOfKind<TKind>; options: TInput }) => Promise<SharedCacheAdapter<TData>>)
+    | ((
+        input: { integration: IntegrationOfKind<TKind>; options: TInput },
+        cacheIdentity: string,
+      ) => Promise<SharedCacheAdapter<TData>>)
     | undefined;
   if (cacheNamespace) {
-    getSharedCacheAsync = async ({ integration, options: itemOptions }) =>
+    getSharedCacheAsync = async ({ integration }, cacheIdentity) =>
       await createIntegrationSharedCacheAsync({
         namespace: cacheNamespace,
         integrationId: integration.id,
-        cacheOptions: itemOptions,
+        cacheIdentity,
+        cacheVersion: options.cacheVersion,
       });
   }
 
   const inner = createRequestHandler<TData, { integration: IntegrationOfKind<TKind>; options: TInput }>({
-    requestAsync: async ({ integration, options: itemOptions }) => options.requestAsync(integration, itemOptions),
-    getCacheKey: ({ integration, options: itemOptions }) =>
-      `${integration.id}:${hashIntegrationCacheOptions(itemOptions)}`,
+    requestAsync: async ({ integration, options: itemOptions }, signal) =>
+      options.requestAsync(integration, itemOptions, signal),
+    getCacheKey: getIntegrationCacheIdentity,
     cacheTtlMs: options.cacheTtlMs,
     fallbackToStaleOnError: options.fallbackToStaleOnError,
     staleIfErrorTtlMs: options.staleIfErrorTtlMs,
+    requestTimeoutMs: options.requestTimeoutMs,
     getSharedCacheAsync,
   });
 

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

@@ -1,10 +1,11 @@
 interface Options<TData, TInput extends Record<string, unknown>> {
-  requestAsync: (input: TInput) => Promise<TData>;
+  requestAsync: (input: TInput, signal: AbortSignal) => Promise<TData>;
   getCacheKey?: (input: TInput) => string;
   cacheTtlMs?: number;
   fallbackToStaleOnError?: boolean;
   staleIfErrorTtlMs?: number;
-  getSharedCacheAsync?: (input: TInput) => Promise<SharedCacheAdapter<TData>>;
+  requestTimeoutMs?: number;
+  getSharedCacheAsync?: (input: TInput, cacheIdentity: string) => Promise<SharedCacheAdapter<TData>>;
 }
 
 export interface CacheEntry<TData> {
@@ -18,25 +19,63 @@ export interface SharedCacheAdapter<TData> {
   generation: string;
   isShared: boolean;
   getAsync: () => Promise<CacheEntry<TData> | null | undefined>;
-  setAsync: (entry: CacheEntry<TData>) => Promise<void>;
+  setAsync: (entry: CacheEntry<TData>, refreshLockToken: string) => Promise<boolean | void>;
   acquireRefreshLockAsync: () => Promise<string | null | undefined>;
   renewRefreshLockAsync: (token: string) => Promise<boolean | undefined>;
   releaseRefreshLockAsync: (token: string) => Promise<void>;
 }
 
 const MAX_CACHE_SIZE = 1000;
+const MAX_INFLIGHT_REQUESTS = 100;
+const MAX_UPSTREAM_SETTLEMENT_GRACE_MS = 60_000;
 const DEFAULT_TTL_MS = 10_000;
 const DEFAULT_STALE_IF_ERROR_TTL_MS = 5 * 60_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 const SHARED_REFRESH_POLL_MS = 100;
 const SHARED_REFRESH_LOCK_RETRY_MS = 1_000;
 const SHARED_REFRESH_STALE_WAIT_MS = 15_000;
+const SHARED_REFRESH_MAX_WAIT_MS = 30_000;
 // Must remain comfortably below REFRESH_LOCK_TTL_SECONDS in shared-cache.ts.
 const SHARED_REFRESH_LOCK_RENEW_MS = 5_000;
 
-const delayAsync = async (durationMs: number) =>
+class RequestHandlerTimeoutError extends Error {
+  constructor() {
+    super("Request handler deadline exceeded");
+    this.name = RequestHandlerTimeoutError.name;
+  }
+}
+
+class RequestHandlerOverloadedError extends Error {
+  constructor() {
+    super("Request handler concurrency limit exceeded");
+    this.name = RequestHandlerOverloadedError.name;
+  }
+}
+
+const throwIfDeadlineExceeded = (deadlineAt: number) => {
+  if (Date.now() >= deadlineAt) throw new RequestHandlerTimeoutError();
+};
+
+const delayAsync = async (durationMs: number, deadlineAt: number) => {
+  throwIfDeadlineExceeded(deadlineAt);
+  const remainingMs = deadlineAt - Date.now();
   await new Promise<void>((resolve) => {
-    setTimeout(resolve, durationMs);
+    const timer = setTimeout(resolve, Math.min(durationMs, remainingMs));
+    timer.unref?.();
   });
+  throwIfDeadlineExceeded(deadlineAt);
+};
+
+const waitForSettlementGraceAsync = async (settledAsync: Promise<void>, durationMs: number) => {
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, durationMs);
+    timer.unref?.();
+    void settledAsync.then(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+};
 
 const startRefreshLockRenewal = <TData>(sharedCache: SharedCacheAdapter<TData>, token: string) => {
   let isOwned = true;
@@ -81,8 +120,15 @@ const evictExpired = <TData>(cache: Map<string, CacheEntry<TData>>) => {
 export const createRequestHandler = <TData, TInput extends Record<string, unknown>>(
   options: Options<TData, TInput>,
 ) => {
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+    throw new Error("Request timeout must be a positive finite duration");
+  }
+
   const cache = new Map<string, CacheEntry<TData>>();
   const inflight = new Map<string, Promise<CacheEntry<TData>>>();
+  const sharedCacheResolutions = new Map<string, Promise<SharedCacheAdapter<TData>>>();
+  const upstreamSettlements = new Map<string, Promise<void>>();
   let expiryTimer: ReturnType<typeof setTimeout> | undefined;
   let expiryTimerAt: number | undefined;
   let generation = 0;
@@ -90,6 +136,7 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
   const storeInMemory = (key: string, entry: CacheEntry<TData>, requestGeneration: number) => {
     if (generation !== requestGeneration || Date.now() >= entry.staleUntil) return;
     evictExpired(cache);
+    cache.delete(key);
     if (cache.size >= MAX_CACHE_SIZE) {
       const oldest = cache.keys().next().value;
       if (oldest !== undefined) cache.delete(oldest);
@@ -98,6 +145,64 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
     scheduleExpiry(entry.staleUntil);
   };
 
+  const getFromMemory = (key: string) => {
+    const entry = cache.get(key);
+    if (!entry) return undefined;
+    cache.delete(key);
+    cache.set(key, entry);
+    return entry;
+  };
+
+  const startRequestWithDeadline = (input: TInput, deadlineAt: number, upstreamKey: string) => {
+    throwIfDeadlineExceeded(deadlineAt);
+    if (upstreamSettlements.has(upstreamKey) || upstreamSettlements.size >= MAX_INFLIGHT_REQUESTS) {
+      throw new RequestHandlerOverloadedError();
+    }
+
+    const controller = new AbortController();
+    const timeoutError = new RequestHandlerTimeoutError();
+    const remainingMs = deadlineAt - Date.now();
+    const upstreamRequest = Promise.resolve().then(async () => await options.requestAsync(input, controller.signal));
+    const settledAsync = upstreamRequest.then(
+      () => undefined,
+      () => undefined,
+    );
+    upstreamSettlements.set(upstreamKey, settledAsync);
+    void settledAsync.then(() => {
+      if (upstreamSettlements.get(upstreamKey) === settledAsync) upstreamSettlements.delete(upstreamKey);
+    });
+
+    const resultAsync = new Promise<TData>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        controller.abort(timeoutError);
+        reject(timeoutError);
+      }, remainingMs);
+      timer.unref?.();
+
+      void upstreamRequest.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+
+    return { resultAsync, settledAsync };
+  };
+
+  const resolveSharedCacheAsync = (input: TInput, cacheIdentity: string, requestGeneration: number) => {
+    if (!options.getSharedCacheAsync) return undefined;
+
+    const resolutionKey = `${requestGeneration}:${cacheIdentity}`;
+    const existing = sharedCacheResolutions.get(resolutionKey);
+    if (existing) return existing;
+    if (sharedCacheResolutions.size >= MAX_INFLIGHT_REQUESTS) {
+      throw new RequestHandlerOverloadedError();
+    }
+
+    let promise: Promise<SharedCacheAdapter<TData>>;
+    promise = options.getSharedCacheAsync(input, cacheIdentity).finally(() => {
+      if (sharedCacheResolutions.get(resolutionKey) === promise) sharedCacheResolutions.delete(resolutionKey);
+    });
+    sharedCacheResolutions.set(resolutionKey, promise);
+    return promise;
+  };
+
   const scheduleExpiry = (candidateExpiryAt?: number) => {
     if (candidateExpiryAt !== undefined && expiryTimerAt !== undefined && expiryTimerAt <= candidateExpiryAt) return;
     if (expiryTimer) clearTimeout(expiryTimer);
@@ -123,36 +228,43 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
     invalidateCache: () => {
       generation += 1;
       cache.clear();
-      inflight.clear();
       if (expiryTimer) clearTimeout(expiryTimer);
       expiryTimer = undefined;
       expiryTimerAt = undefined;
     },
     handler: (input: TInput) => ({
       async getDataAsync(): Promise<{ data: TData; timestamp: Date }> {
+        const deadlineAt = Date.now() + requestTimeoutMs;
         const ttl = options.cacheTtlMs ?? DEFAULT_TTL_MS;
         const baseKey = options.getCacheKey?.(input) ?? JSON.stringify(input);
-        const existing = inflight.get(baseKey);
+        const requestGeneration = generation;
+        let sharedCache: SharedCacheAdapter<TData> | undefined;
+        if (ttl > 0) {
+          sharedCache = await resolveSharedCacheAsync(input, baseKey, requestGeneration);
+          throwIfDeadlineExceeded(deadlineAt);
+        }
+
+        const key = `${sharedCache?.generation ?? "local"}:${baseKey}`;
+        const inflightKey = `${requestGeneration}:${key}`;
+        const existing = inflight.get(inflightKey);
         if (existing) return existing;
 
-        const requestGeneration = generation;
+        let cached = getFromMemory(key);
+        const now = Date.now();
+        if (cached && now < cached.expiresAt) return cached;
+        if (cached && now >= cached.staleUntil) {
+          cache.delete(key);
+          scheduleExpiry();
+          cached = undefined;
+        }
+        if (upstreamSettlements.has(inflightKey) || inflight.size >= MAX_INFLIGHT_REQUESTS) {
+          if (options.fallbackToStaleOnError && cached) return cached;
+          throw new RequestHandlerOverloadedError();
+        }
+
+        let cleanupAfterUpstreamAsync: Promise<void> | undefined;
         let promise: Promise<CacheEntry<TData>>;
         promise = (async () => {
-          let sharedCache: SharedCacheAdapter<TData> | undefined;
-          if (ttl > 0 && options.getSharedCacheAsync) {
-            sharedCache = await options.getSharedCacheAsync(input);
-          }
-          const key = `${sharedCache?.generation ?? "local"}:${baseKey}`;
-
-          let cached = cache.get(key);
-          const now = Date.now();
-          if (cached && now < cached.expiresAt) return cached;
-          if (cached && now >= cached.staleUntil) {
-            cache.delete(key);
-            scheduleExpiry();
-            cached = undefined;
-          }
-
           let stale = cached;
           let lockToken: string | null | undefined;
 
@@ -167,9 +279,10 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
             lockToken = await sharedCache.acquireRefreshLockAsync();
             if (lockToken === null) {
               const returnStaleAt = Date.now() + SHARED_REFRESH_STALE_WAIT_MS;
+              const waitDeadlineAt = Math.min(deadlineAt, Date.now() + SHARED_REFRESH_MAX_WAIT_MS);
               let retryLockAt = Date.now() + SHARED_REFRESH_LOCK_RETRY_MS;
               while (lockToken === null && sharedCache.isShared) {
-                await delayAsync(SHARED_REFRESH_POLL_MS);
+                await delayAsync(SHARED_REFRESH_POLL_MS, waitDeadlineAt);
                 const refreshedEntry = await sharedCache.getAsync();
                 if (refreshedEntry && Date.now() < refreshedEntry.expiresAt) {
                   storeInMemory(key, refreshedEntry, requestGeneration);
@@ -190,8 +303,11 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
 
           const refreshLockRenewal =
             lockToken && sharedCache ? startRefreshLockRenewal(sharedCache, lockToken) : undefined;
+          let upstreamSettledAsync: Promise<void> | undefined;
           try {
-            const data = await options.requestAsync(input);
+            const request = startRequestWithDeadline(input, deadlineAt, inflightKey);
+            upstreamSettledAsync = request.settledAsync;
+            const data = await request.resultAsync;
             const completedAt = Date.now();
             const staleIfErrorTtlMs = options.fallbackToStaleOnError
               ? Math.max(0, options.staleIfErrorTtlMs ?? DEFAULT_STALE_IF_ERROR_TTL_MS)
@@ -203,10 +319,15 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
               staleUntil: completedAt + ttl + staleIfErrorTtlMs,
             };
             if (ttl > 0) {
-              storeInMemory(key, entry, requestGeneration);
-              if (sharedCache?.isShared && refreshLockRenewal?.isOwned() !== false) {
-                await sharedCache.setAsync(entry);
+              let canStoreInMemory = true;
+              if (sharedCache?.isShared) {
+                canStoreInMemory = false;
+                if (lockToken && refreshLockRenewal?.isOwned() !== false) {
+                  const stored = await sharedCache.setAsync(entry, lockToken);
+                  if (stored !== false || !sharedCache.isShared) canStoreInMemory = true;
+                }
               }
+              if (canStoreInMemory) storeInMemory(key, entry, requestGeneration);
             }
             return entry;
           } catch (error) {
@@ -221,14 +342,34 @@ export const createRequestHandler = <TData, TInput extends Record<string, unknow
             }
             throw error;
           } finally {
-            refreshLockRenewal?.stop();
-            if (lockToken) await sharedCache?.releaseRefreshLockAsync(lockToken);
+            const cleanupAsync = async () => {
+              refreshLockRenewal?.stop();
+              if (lockToken) await sharedCache?.releaseRefreshLockAsync(lockToken);
+            };
+            if (upstreamSettledAsync) {
+              const settlementGraceMs = Math.min(requestTimeoutMs, MAX_UPSTREAM_SETTLEMENT_GRACE_MS);
+              cleanupAfterUpstreamAsync = waitForSettlementGraceAsync(upstreamSettledAsync, settlementGraceMs).then(
+                cleanupAsync,
+              );
+            } else {
+              await cleanupAsync();
+            }
           }
-        })().finally(() => {
-          if (inflight.get(baseKey) === promise) inflight.delete(baseKey);
-        });
+        })();
 
-        inflight.set(baseKey, promise);
+        inflight.set(inflightKey, promise);
+        const removeInflight = () => {
+          const cleanupAsync = cleanupAfterUpstreamAsync ?? Promise.resolve();
+          void cleanupAsync.then(
+            () => {
+              if (inflight.get(inflightKey) === promise) inflight.delete(inflightKey);
+            },
+            () => {
+              if (inflight.get(inflightKey) === promise) inflight.delete(inflightKey);
+            },
+          );
+        };
+        void promise.then(removeInflight, removeInflight);
         return promise;
       },
     }),

packages/request-handler/src/lib/shared-cache.ts

@@ -15,9 +15,14 @@ import type { IntegrationCacheGeneration, WidgetCacheGeneration } from "@homarr/
 import type { CacheEntry, SharedCacheAdapter } from "./request-handler";
 
 const logger = createLogger({ module: "sharedRequestCache" });
-const REDIS_OPERATION_TIMEOUT_MS = 250;
+// The dedicated cache client rejects commands after 500 ms. This guard stays
+// above that deadline so lock outcomes are never abandoned while still pending.
+const REDIS_OPERATION_TIMEOUT_MS = 750;
 const REFRESH_LOCK_TTL_SECONDS = 15;
+const SHARED_CACHE_ENVELOPE_VERSION = 2;
+const DEFAULT_HANDLER_CACHE_VERSION = "v1";
 const namespacePattern = /^[a-z0-9][a-z0-9:-]*$/;
+const cacheVersionPattern = /^[a-z0-9][a-z0-9._-]*$/;
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === "object" && !Array.isArray(value);
 
@@ -47,27 +52,40 @@ const withTimeoutAsync = async <T>(promise: Promise<T>, durationMs: number): Pro
   });
 };
 
-const isCacheEntry = (value: unknown): value is CacheEntry<unknown> => {
-  if (!isRecord(value)) return false;
+interface SharedCacheEnvelope<TData> {
+  version: typeof SHARED_CACHE_ENVELOPE_VERSION;
+  entry: CacheEntry<TData>;
+}
+
+const isSharedCacheEnvelope = (value: unknown): value is SharedCacheEnvelope<unknown> => {
+  if (!isRecord(value) || value.version !== SHARED_CACHE_ENVELOPE_VERSION || !isRecord(value.entry)) return false;
+
+  const entry = value.entry;
+  if (!Object.hasOwn(entry, "data") || !(entry.timestamp instanceof Date)) return false;
+  const timestamp = entry.timestamp.getTime();
   return (
-    value.timestamp instanceof Date &&
-    typeof value.expiresAt === "number" &&
-    Number.isFinite(value.expiresAt) &&
-    typeof value.staleUntil === "number" &&
-    Number.isFinite(value.staleUntil)
+    Number.isFinite(timestamp) &&
+    typeof entry.expiresAt === "number" &&
+    Number.isFinite(entry.expiresAt) &&
+    typeof entry.staleUntil === "number" &&
+    Number.isFinite(entry.staleUntil) &&
+    timestamp <= entry.expiresAt &&
+    entry.expiresAt <= entry.staleUntil
   );
 };
 
 interface IntegrationSharedCacheOptions {
   namespace: string;
   integrationId: string;
-  cacheOptions: Record<string, unknown>;
+  cacheIdentity: string;
+  cacheVersion?: string;
 }
 
 interface RedisSharedCacheOptions {
   namespace: string;
   cacheKind: "integration" | "widget";
   cacheIdentity: string;
+  cacheVersion: string;
   generation: string;
   metadata?: Record<string, string>;
   isShared?: boolean;
@@ -90,15 +108,16 @@ const createRedisSharedCache = <TData>({
   namespace,
   cacheKind,
   cacheIdentity,
+  cacheVersion,
   generation,
   metadata = {},
   isShared: initialIsShared = true,
 }: RedisSharedCacheOptions): SharedCacheAdapter<TData> => {
   const logMetadata = { cacheNamespace: namespace, cacheKind, ...metadata };
-  const payloadChannel = createGetSetChannel<CacheEntry<TData>>(
-    `${cacheKind}-cache:payload:v1:${namespace}:${generation}:${cacheIdentity}`,
-  );
-  const lock = createLockChannel(`${cacheKind}-cache:lock:v1:${namespace}:${generation}:${cacheIdentity}`);
+  const payloadName = `${cacheKind}-cache:payload:v2:${cacheVersion}:${namespace}:${generation}:${cacheIdentity}`;
+  const lockName = `${cacheKind}-cache:lock:v2:${cacheVersion}:${namespace}:${generation}:${cacheIdentity}`;
+  const payloadChannel = createGetSetChannel<unknown>(payloadName, { useBoundedCacheClient: true });
+  const lock = createLockChannel(lockName, { useBoundedCacheClient: true });
   let isShared = initialIsShared;
 
   const runRedisOperationAsync = async <T>(operation: string, callback: () => Promise<T>, fallback: T): Promise<T> => {
@@ -120,7 +139,7 @@ const createRedisSharedCache = <TData>({
     getAsync: async () => {
       const value = await runRedisOperationAsync("payload-read", () => payloadChannel.getAsync(), undefined);
       if (value === undefined || value === null) return value;
-      if (isCacheEntry(value)) return value;
+      if (isSharedCacheEnvelope(value)) return value.entry as CacheEntry<TData>;
 
       logger.warn("Ignored invalid Redis response cache entry", {
         ...logMetadata,
@@ -129,12 +148,16 @@ const createRedisSharedCache = <TData>({
       await runRedisOperationAsync("payload-remove", () => payloadChannel.removeAsync(), undefined);
       return null;
     },
-    setAsync: async (entry) => {
+    setAsync: async (entry, refreshLockToken) => {
       const retentionMs = entry.staleUntil - Date.now();
-      if (retentionMs <= 0) return;
-      await runRedisOperationAsync(
+      if (retentionMs <= 0) return false;
+      const envelope: SharedCacheEnvelope<TData> = {
+        version: SHARED_CACHE_ENVELOPE_VERSION,
+        entry,
+      };
+      return await runRedisOperationAsync(
         "payload-write",
-        () => payloadChannel.setAsync(entry, { ttlMs: retentionMs }),
+        () => lock.setIfOwnedAsync(refreshLockToken, payloadName, envelope, retentionMs),
         undefined,
       );
     },
@@ -151,22 +174,29 @@ const createRedisSharedCache = <TData>({
         undefined,
       ),
     releaseRefreshLockAsync: async (token) => {
-      await runRedisOperationAsync("refresh-lock-release", () => lock.releaseAsync(token), undefined);
+      try {
+        await withTimeoutAsync(lock.releaseAsync(token), REDIS_OPERATION_TIMEOUT_MS);
+      } catch (error) {
+        logRedisFailure("refresh-lock-release", logMetadata, error);
+      }
     },
   };
 };
 
 interface WidgetSharedCacheOptions {
   namespace: string;
-  cacheInput: Record<string, unknown>;
+  cacheIdentity: string;
+  cacheVersion?: string;
 }
 
 export const createWidgetSharedCacheAsync = async <TData>({
   namespace,
-  cacheInput,
+  cacheIdentity,
+  cacheVersion = DEFAULT_HANDLER_CACHE_VERSION,
 }: WidgetSharedCacheOptions): Promise<SharedCacheAdapter<TData>> => {
   if (typeof window !== "undefined") throw new Error("Widget request caching is server-only");
   if (!namespacePattern.test(namespace)) throw new Error(`Invalid widget cache namespace '${namespace}'`);
+  if (!cacheVersionPattern.test(cacheVersion)) throw new Error(`Invalid widget cache version '${cacheVersion}'`);
 
   const metadata = { cacheNamespace: namespace };
   let generation: WidgetCacheGeneration;
@@ -180,7 +210,8 @@ export const createWidgetSharedCacheAsync = async <TData>({
   return createRedisSharedCache<TData>({
     namespace,
     cacheKind: "widget",
-    cacheIdentity: hashSharedCacheInput(cacheInput),
+    cacheIdentity,
+    cacheVersion,
     generation: generation.value,
     isShared: generation.isShared,
   });
@@ -189,10 +220,12 @@ export const createWidgetSharedCacheAsync = async <TData>({
 export const createIntegrationSharedCacheAsync = async <TData>({
   namespace,
   integrationId,
-  cacheOptions,
+  cacheIdentity,
+  cacheVersion = DEFAULT_HANDLER_CACHE_VERSION,
 }: IntegrationSharedCacheOptions): Promise<SharedCacheAdapter<TData>> => {
   if (typeof window !== "undefined") throw new Error("Integration request caching is server-only");
   if (!namespacePattern.test(namespace)) throw new Error(`Invalid integration cache namespace '${namespace}'`);
+  if (!cacheVersionPattern.test(cacheVersion)) throw new Error(`Invalid integration cache version '${cacheVersion}'`);
 
   const metadata = { cacheNamespace: namespace, integrationId };
   let generation: IntegrationCacheGeneration;
@@ -203,11 +236,11 @@ export const createIntegrationSharedCacheAsync = async <TData>({
     generation = { value: "redis-unavailable", isShared: false };
   }
 
-  const optionsHash = hashIntegrationCacheOptions(cacheOptions);
   const sharedCache = createRedisSharedCache<TData>({
     namespace,
     cacheKind: "integration",
-    cacheIdentity: `${integrationId}:${optionsHash}`,
+    cacheIdentity,
+    cacheVersion,
     generation: generation.value,
     metadata: { integrationId },
     isShared: generation.isShared,

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

@@ -5,23 +5,26 @@ import { createRequestHandler } from "./request-handler";
 import type { SharedCacheAdapter } from "./request-handler";
 
 interface Options<TData, TInput extends Record<string, unknown>> {
-  requestAsync: (input: TInput) => Promise<TData>;
+  requestAsync: (input: TInput, signal: AbortSignal) => Promise<TData>;
   cacheTtlMs?: number;
   fallbackToStaleOnError?: boolean;
   staleIfErrorTtlMs?: number;
+  requestTimeoutMs?: number;
   cacheNamespace?: string;
+  cacheVersion?: string;
 }
 
 export const createWidgetRequestHandler = <TData, TInput extends Record<string, unknown>>(
   options: Options<TData, TInput>,
 ) => {
   const cacheNamespace = options.cacheNamespace;
-  let getSharedCacheAsync: ((input: TInput) => Promise<SharedCacheAdapter<TData>>) | undefined;
+  let getSharedCacheAsync: ((input: TInput, cacheIdentity: string) => Promise<SharedCacheAdapter<TData>>) | undefined;
   if (cacheNamespace) {
-    getSharedCacheAsync = async (input) =>
+    getSharedCacheAsync = async (_input, cacheIdentity) =>
       await createWidgetSharedCacheAsync<TData>({
         namespace: cacheNamespace,
-        cacheInput: input,
+        cacheIdentity,
+        cacheVersion: options.cacheVersion,
       });
   }
 
@@ -30,6 +33,7 @@ export const createWidgetRequestHandler = <TData, TInput extends Record<string,
     cacheTtlMs: options.cacheTtlMs,
     fallbackToStaleOnError: options.fallbackToStaleOnError,
     staleIfErrorTtlMs: options.staleIfErrorTtlMs,
+    requestTimeoutMs: options.requestTimeoutMs,
     getCacheKey: hashSharedCacheInput,
     getSharedCacheAsync,
   });

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

@@ -1,18 +1,16 @@
 import { z } from "zod/v4";
 
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
-import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
 
 import { createWidgetRequestHandler } from "./lib/widget-request-handler";
 
 export const minecraftServerStatusRequestHandler = createWidgetRequestHandler({
-  cacheNamespace: "minecraft-server-status",
-  async requestAsync(input: { domain: string; isBedrockServer: boolean }) {
+  // Domains are supplied through a public procedure and form an unbounded key space.
+  requestTimeoutMs: 10_000,
+  async requestAsync(input: { domain: string; isBedrockServer: boolean }, signal) {
     const path = `${input.isBedrockServer ? "/bedrock" : ""}/3/${input.domain}`;
 
-    const response = await withTimeoutAsync(async (signal) =>
-      fetchWithTrustedCertificatesAsync(`https://api.mcsrvstat.us${path}`, { signal }),
-    );
+    const response = await fetchWithTrustedCertificatesAsync(`https://api.mcsrvstat.us${path}`, { signal });
     return responseSchema.parse(await response.json());
   },
 });

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

@@ -10,19 +10,23 @@ import { createWidgetRequestHandler } from "./lib/widget-request-handler";
 const logger = createLogger({ module: "rssFeedsRequestHandler" });
 
 export const rssFeedsRequestHandler = createWidgetRequestHandler({
-  cacheNamespace: "rss-feeds",
-  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,
-        };
+  // Authorized editors can supply arbitrary URLs, so keep this cache process-local and bounded.
+  async requestAsync(input: { url: string; count: number }, signal) {
+    const result = (await extract(
+      input.url,
+      {
+        getExtraEntryFields: (feedEntry) => {
+          const media = attemptGetImageFromEntry(input.url, feedEntry);
+          if (!media) {
+            return {};
+          }
+          return {
+            enclosure: media,
+          };
+        },
       },
-    })) as ExtendedFeedData;
+      { signal },
+    )) as ExtendedFeedData;
 
     return {
       ...result,

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

@@ -1,19 +1,17 @@
 import { z } from "zod/v4";
 
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
-import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
 
 import { createWidgetRequestHandler } from "./lib/widget-request-handler";
 
 export const fetchStockPriceHandler = createWidgetRequestHandler({
-  cacheNamespace: "stock-price",
-  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 },
-      );
-    });
+  // Symbols are supplied through a public procedure and form an unbounded key space.
+  requestTimeoutMs: 10_000,
+  async requestAsync(input: { stock: string; timeRange: string; timeInterval: string }, signal) {
+    const response = 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) {

packages/request-handler/src/weather.ts

@@ -5,7 +5,6 @@ import { z } from "zod";
 
 import { ResponseError } from "@homarr/common/server";
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
-import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
 
 import { createWidgetRequestHandler } from "./lib/widget-request-handler";
 
@@ -15,7 +14,10 @@ dayjs.extend(timezone);
 const HOURLY_FORECAST_LENGTH = 24;
 const DAILY_FORECAST_LENGTH = 7;
 
-const requestWeatherAsync = async (input: { latitude: number; longitude: number }): Promise<Weather> => {
+const requestWeatherAsync = async (
+  input: { latitude: number; longitude: number },
+  signal: AbortSignal,
+): Promise<Weather> => {
   const url = new URL("https://api.open-meteo.com/v1/forecast");
   url.searchParams.set("latitude", input.latitude.toString());
   url.searchParams.set("longitude", input.longitude.toString());
@@ -68,9 +70,7 @@ const requestWeatherAsync = async (input: { latitude: number; longitude: number
   url.searchParams.set("forecast_hours", HOURLY_FORECAST_LENGTH.toString());
   url.searchParams.set("forecast_days", DAILY_FORECAST_LENGTH.toString());
 
-  const res = await withTimeoutAsync(async (signal) => {
-    return await fetchWithTrustedCertificatesAsync(url.toString(), { signal });
-  });
+  const res = await fetchWithTrustedCertificatesAsync(url.toString(), { signal });
   if (!res.ok) throw new ResponseError(res);
 
   const json: unknown = await res.json();
@@ -140,8 +140,9 @@ const requestWeatherAsync = async (input: { latitude: number; longitude: number
 };
 
 export const weatherRequestHandler = createWidgetRequestHandler({
-  cacheNamespace: "weather:at-location",
+  // Coordinates are a public, continuous key space. Keep this cache process-local and bounded.
   cacheTtlMs: 5 * 60 * 1000,
+  requestTimeoutMs: 10_000,
   requestAsync: requestWeatherAsync,
 });