Feature: feeds widget (#7170)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/crowdin.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Checkout
       uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
     - name: crowdin action
-      uses: crowdin/github-action@0d5670f539973aea2f01abce61a8989934df0025 # v3.0.2
+      uses: crowdin/github-action@9af557de76d70c480f88065d336f445a362f402b # v3.1.0
       with:
         upload_translations: false
         download_translations: true

.github/workflows/docker-publish.yml

@@ -99,14 +99,14 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Setup QEMU
-        uses: docker/setup-qemu-action@1f40c72289eff860ee54a304f1438e3cff362e0a # v4.3.0
+        uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
 
       - name: Setup Docker buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4
 
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}

.github/workflows/test.yml

@@ -31,7 +31,7 @@ jobs:
       # Run Vitest directly so `--shard` is parsed as an option
       - run: pnpm -s exec vitest run --coverage --shard ${{ matrix.shard }}/4 --pool forks
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage/lcov.info

docs/widgets/services/arcane.md

@@ -6,6 +6,7 @@ description: Arcane Widget Configuration
 Learn more about [Arcane](https://github.com/getarcaneapp/arcane).
 
 **Allowed fields** (max 4): `running`, `stopped`, `total`, `images`, `images_used`, `images_unused`, `image_updates`.
+
 **Default fields**: `running`, `stopped`, `total`, `image_updates`.
 
 ```yaml
@@ -17,4 +18,4 @@ widget:
   fields: ["running", "stopped", "total", "image_updates"] # optional
 ```
 
-Using an api key for the widget requires permissions for: `containers:list` `images:list and `image-updates:read`
+Using an API key for the widget requires permissions for: `containers:list`, `images:list`, and `image-updates:read`.

docs/widgets/services/feed.md

@@ -0,0 +1,46 @@
+---
+title: Feed
+description: RSS / Atom feed widget
+---
+
+This widget shows the latest items from an RSS 2.0 or Atom feed.
+
+```yaml
+widget:
+  type: feed
+  url: https://feeds.bbci.co.uk/news/rss.xml
+  maxItems: 5 # optional - defaults to 5
+  layout: list # optional - possible values list, grid - defaults to list
+  images: true # optional - set to false to hide images - defaults to true
+```
+
+## Layouts
+
+`list` shows one row per item. Items with an image get a small thumbnail.
+
+![Feed widget list layout](../../assets/widget_feed_list.webp)
+
+![Feed widget list layout with thumbnails](../../assets/widget_feed_thumbnails.webp)
+
+`grid` shows image tiles that re-flow to fit the width of the widget, e.g.:
+
+```yaml
+- NASA Image of the Day:
+    widget:
+      type: feed
+      url: https://www.nasa.gov/feeds/iotd-feed/
+      layout: grid
+      maxItems: 8
+```
+
+![Feed widget grid layout](../../assets/widget_feed_grid.webp)
+
+## Images
+
+Images are taken from the feed's `media:thumbnail` / `media:content` tags or image enclosures, falling back to the first image in the item's content. Some feeds do not include images at all.
+
+Images are loaded by your browser directly from the feed's host, at whatever size the feed provides. Feeds that link full-size originals can be slow to load; set `images: false` for those.
+
+## Notes
+
+Feeds are fetched by homepage, not your browser, and cached for 10 minutes.

docs/widgets/services/index.md

@@ -39,6 +39,7 @@ You can also find a list of all available service widgets in the sidebar navigat
 - [Emby](emby.md)
 - [ESPHome](esphome.md)
 - [EVCC](evcc.md)
+- [Feed](feed.md)
 - [Filebrowser](filebrowser.md)
 - [Fileflows](fileflows.md)
 - [Firefly III](firefly.md)

mkdocs.yml

@@ -65,6 +65,7 @@ nav:
           - widgets/services/emby.md
           - widgets/services/esphome.md
           - widgets/services/evcc.md
+          - widgets/services/feed.md
           - widgets/services/filebrowser.md
           - widgets/services/fileflows.md
           - widgets/services/firefly.md

package.json

@@ -39,6 +39,7 @@
     "react-i18next": "^17.0.12",
     "react-icons": "^5.6.0",
     "recharts": "^3.1.2",
+    "sax": "^1.6.1",
     "swr": "^2.5.1",
     "systeminformation": "^5.33.1",
     "tough-cookie": "^6.0.2",

pnpm-lock.yaml

@@ -83,6 +83,9 @@ importers:
       recharts:
         specifier: ^3.1.2
         version: 3.10.1(@types/react@19.2.18)(react-dom@19.2.8(react@19.2.8))(react-is@17.0.2)(react@19.2.8)(redux@5.0.1)
+      sax:
+        specifier: ^1.6.1
+        version: 1.6.1
       swr:
         specifier: ^2.5.1
         version: 2.5.1(react@19.2.8)

public/locales/en/common.json

@@ -1258,5 +1258,8 @@
         "wanted": "Wanted",
         "queued": "Queued",
         "leagues": "Leagues"
+    },
+    "feed": {
+        "noItems": "No items"
     }
 }

src/utils/config/service-helpers.js

@@ -353,6 +353,9 @@ export function cleanServiceGroups(groups) {
           expandOneStreamToTwoRows,
           showEpisodeNumber,
 
+          // feed
+          layout,
+
           // frigate
           enableRecentEvents,
 
@@ -675,6 +678,9 @@ export function cleanServiceGroups(groups) {
           if (showTime) widget.showTime = showTime;
           if (timezone) widget.timezone = timezone;
         }
+        if (type === "feed") {
+          if (layout) widget.layout = layout;
+        }
         if (type === "dockhand") {
           if (environment) widget.environment = environment;
         }

src/utils/config/service-helpers.test.js

@@ -524,6 +524,38 @@ describe("utils/config/service-helpers", () => {
     ]);
   });
 
+  it("cleanServiceGroups keeps feed layout and drops server-side options", async () => {
+    const mod = await import("./service-helpers");
+    const { cleanServiceGroups } = mod;
+
+    const rawGroups = [
+      {
+        name: "Core",
+        services: [
+          {
+            name: "News",
+            widgets: [
+              {
+                type: "feed",
+                url: "https://example.com/feed.xml?token=secret",
+                maxItems: 3,
+                images: false,
+                layout: "grid",
+              },
+            ],
+          },
+        ],
+        groups: [],
+      },
+    ];
+
+    const feedWidget = cleanServiceGroups(rawGroups)[0].services[0].widgets[0];
+    expect(feedWidget).toEqual(expect.objectContaining({ type: "feed", layout: "grid" }));
+    expect(feedWidget).not.toHaveProperty("url");
+    expect(feedWidget).not.toHaveProperty("maxItems");
+    expect(feedWidget).not.toHaveProperty("images");
+  });
+
   it("findGroupByName deep-searches and annotates parent", async () => {
     const mod = await import("./service-helpers");
     const { findGroupByName } = mod;

src/widgets/components.js

@@ -37,6 +37,7 @@ const components = {
   emby: dynamic(() => import("./emby/component")),
   esphome: dynamic(() => import("./esphome/component")),
   evcc: dynamic(() => import("./evcc/component")),
+  feed: dynamic(() => import("./feed/component")),
   filebrowser: dynamic(() => import("./filebrowser/component")),
   fileflows: dynamic(() => import("./fileflows/component")),
   firefly: dynamic(() => import("./firefly/component")),

src/widgets/feed/component.jsx

@@ -0,0 +1,125 @@
+/* eslint-disable @next/next/no-img-element */
+import classNames from "classnames";
+import { useTranslation } from "next-i18next/pages";
+import { useContext } from "react";
+
+import Container from "components/services/widget/container";
+import { SettingsContext } from "utils/contexts/settings";
+import useWidgetAPI from "utils/proxy/use-widget-api";
+
+const rowClassName = "rounded-md bg-theme-200/50 dark:bg-theme-900/20 text-theme-700 dark:text-theme-200 text-xs";
+const hideBrokenImage = (e) => {
+  e.currentTarget.style.visibility = "hidden";
+};
+
+function FeedLink({ item, target, className, children }) {
+  if (!item.link) return <div className={className}>{children}</div>;
+  return (
+    <a
+      href={item.link}
+      target={target}
+      rel="noopener noreferrer"
+      className={classNames(className, "hover:bg-theme-300/50 dark:hover:bg-theme-800/20")}
+    >
+      {children}
+    </a>
+  );
+}
+
+function RelativeDate({ date }) {
+  const { t } = useTranslation();
+  if (!date) return null;
+  return (
+    <span className="shrink-0 text-theme-500 dark:text-theme-400">
+      {t("common.relativeDate", { value: date, formatParams: { value: { style: "narrow", numeric: "auto" } } })}
+    </span>
+  );
+}
+
+function ListItem({ item, target }) {
+  return (
+    <FeedLink
+      item={item}
+      target={target}
+      className={classNames(rowClassName, "flex items-center gap-2 px-2", item.image ? "py-1" : "h-5")}
+    >
+      {item.image && (
+        <img
+          src={item.image}
+          alt=""
+          loading="lazy"
+          decoding="async"
+          referrerPolicy="no-referrer"
+          onError={hideBrokenImage}
+          className="w-12 h-8 shrink-0 rounded-sm object-cover"
+        />
+      )}
+      <span className="grow truncate text-left">{item.title}</span>
+      <RelativeDate date={item.date} />
+    </FeedLink>
+  );
+}
+
+function GridItem({ item, target }) {
+  return (
+    <FeedLink item={item} target={target} className={classNames(rowClassName, "flex flex-col overflow-hidden")}>
+      <div className="relative aspect-video w-full overflow-hidden bg-theme-200/50 dark:bg-theme-900/30">
+        {item.image && (
+          <img
+            src={item.image}
+            alt=""
+            loading="lazy"
+            decoding="async"
+            referrerPolicy="no-referrer"
+            onError={hideBrokenImage}
+            className="absolute inset-0 w-full h-full object-cover"
+          />
+        )}
+      </div>
+      <div className="flex flex-col gap-0.5 px-2 py-1.5 text-left">
+        <span className="line-clamp-2">{item.title}</span>
+        <RelativeDate date={item.date} />
+      </div>
+    </FeedLink>
+  );
+}
+
+export default function Component({ service }) {
+  const { t } = useTranslation();
+  const { settings } = useContext(SettingsContext);
+  const { widget } = service;
+
+  const { data, error } = useWidgetAPI(widget, undefined, undefined, { refreshInterval: 10 * 60 * 1000 });
+
+  if (error) {
+    return <Container service={service} error={error} />;
+  }
+
+  const target = service.target ?? settings?.target ?? "_blank";
+  const isGrid = widget.layout === "grid";
+  const Item = isGrid ? GridItem : ListItem;
+
+  let content;
+  if (!data) {
+    content = [0, 1, 2].map((i) => (
+      <div key={i} className={classNames(rowClassName, "animate-pulse", isGrid ? "aspect-video" : "h-5")} />
+    ));
+  } else if (!data.items?.length) {
+    content = <div className={classNames(rowClassName, "h-5 px-2 flex items-center")}>{t("feed.noItems")}</div>;
+  } else {
+    content = data.items.map((item, i) => <Item key={`${item.link ?? item.title}-${i}`} item={item} target={target} />);
+  }
+
+  return (
+    <Container service={service}>
+      <div
+        className={classNames(
+          "w-full p-1",
+          isGrid ? "grid grid-cols-[repeat(auto-fill,minmax(8rem,1fr))] gap-2" : "flex flex-col gap-1",
+        )}
+      >
+        {content}
+      </div>
+    </Container>
+  );
+}

src/widgets/feed/component.test.jsx

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+
+import { screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { renderWithProviders } from "test-utils/render-with-providers";
+
+const { useWidgetAPI } = vi.hoisted(() => ({ useWidgetAPI: vi.fn() }));
+vi.mock("utils/proxy/use-widget-api", () => ({ default: useWidgetAPI }));
+
+import Component from "./component";
+
+const items = [
+  {
+    title: "With image",
+    link: "https://example.com/1",
+    date: "2020-01-01T00:00:00Z",
+    image: "https://example.com/1.jpg",
+  },
+  { title: "No link", link: null, date: null },
+];
+
+function render(widget = {}, settings = {}) {
+  return renderWithProviders(<Component service={{ widget: { type: "feed", ...widget } }} />, {
+    settings: { hideErrors: false, ...settings },
+  });
+}
+
+describe("widgets/feed/component", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("renders placeholders while loading", () => {
+    useWidgetAPI.mockReturnValue({ data: undefined, error: undefined });
+    const { container } = render();
+    expect(container.querySelectorAll(".animate-pulse")).toHaveLength(3);
+  });
+
+  it("renders an error", () => {
+    useWidgetAPI.mockReturnValue({ data: undefined, error: { message: "Invalid feed" } });
+    render();
+    expect(screen.getAllByText(/Invalid feed/).length).toBeGreaterThan(0);
+  });
+
+  it("renders an empty feed", () => {
+    useWidgetAPI.mockReturnValue({ data: { items: [] }, error: undefined });
+    render();
+    expect(screen.getByText("feed.noItems")).toBeInTheDocument();
+  });
+
+  it("renders list items with links and images", () => {
+    useWidgetAPI.mockReturnValue({ data: { items }, error: undefined });
+    const { container } = render({}, { target: "_self" });
+
+    const link = screen.getByText("With image").closest("a");
+    expect(link).toHaveAttribute("href", "https://example.com/1");
+    expect(link).toHaveAttribute("target", "_self");
+    expect(link.querySelector("img")).toHaveAttribute("src", "https://example.com/1.jpg");
+    expect(screen.getByText("No link").closest("a")).toBeNull();
+    expect(container.querySelectorAll("img")).toHaveLength(1);
+  });
+
+  it("renders the grid layout with image placeholders", () => {
+    useWidgetAPI.mockReturnValue({ data: { items }, error: undefined });
+    const { container } = render({ layout: "grid" });
+
+    expect(container.querySelector(".grid")).not.toBeNull();
+    expect(container.querySelectorAll(".aspect-video")).toHaveLength(2);
+    expect(container.querySelectorAll("img")).toHaveLength(1);
+  });
+
+  it("hides images that fail to load", () => {
+    useWidgetAPI.mockReturnValue({ data: { items }, error: undefined });
+    const { container } = render();
+    const img = container.querySelector("img");
+    img.dispatchEvent(new Event("error"));
+    expect(img.style.visibility).toBe("hidden");
+  });
+});

src/widgets/feed/proxy.js

@@ -0,0 +1,61 @@
+import cache from "memory-cache";
+
+import { httpUrl, parseFeed } from "./utils";
+
+import getServiceWidget from "utils/config/service-helpers";
+import createLogger from "utils/logger";
+import { sanitizeErrorURL } from "utils/proxy/api-helpers";
+import { httpProxy } from "utils/proxy/http";
+
+const logger = createLogger("feedProxyHandler");
+const CACHE_MS = 10 * 60 * 1000;
+
+export default async function feedProxyHandler(req, res) {
+  const { group, service, index } = req.query;
+  const widget = await getServiceWidget(group, service, index);
+
+  if (!widget?.url) {
+    return res.status(400).json({ error: "Missing feed URL" });
+  }
+
+  const href = httpUrl(widget.url);
+  if (!href) {
+    return res.status(400).json({ error: "Invalid feed URL" });
+  }
+  const url = new URL(href);
+
+  const cacheKey = `feed:${url.href}`;
+  let items = cache.get(cacheKey);
+
+  if (!items) {
+    const [status, , data] = await httpProxy(url, {
+      headers: {
+        "User-Agent": `gethomepage/${process.env.NEXT_PUBLIC_VERSION || "dev"}`,
+        Accept: "application/rss+xml, application/atom+xml, application/xml;q=0.9, text/xml;q=0.9, */*;q=0.8",
+      },
+    });
+
+    if (status !== 200) {
+      logger.debug("HTTP %d retrieving feed %s//%s%s", status, url.protocol, url.host, url.pathname);
+      return res.status(status).json({ error: { message: "HTTP Error", url: sanitizeErrorURL(url) } });
+    }
+
+    try {
+      items = parseFeed(Buffer.from(data).toString());
+    } catch (e) {
+      logger.debug("Error parsing feed %s//%s%s: %s", url.protocol, url.host, url.pathname, e.message);
+      return res.status(500).json({ error: { message: "Invalid feed", url: sanitizeErrorURL(url) } });
+    }
+
+    // only successful fetches are cached
+    cache.put(cacheKey, items, CACHE_MS);
+  }
+
+  const limit = parseInt(widget.maxItems, 10);
+  const maxItems = limit > 0 ? limit : 5;
+  const showImages = widget.images !== false && widget.images !== "false";
+
+  return res.status(200).json({
+    items: items.slice(0, maxItems).map(({ image, ...item }) => (showImages && image ? { ...item, image } : item)),
+  });
+}

src/widgets/feed/proxy.test.js

@@ -0,0 +1,183 @@
+import cache from "memory-cache";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import createMockRes from "test-utils/create-mock-res";
+
+const { httpProxy, getServiceWidget, logger } = vi.hoisted(() => ({
+  httpProxy: vi.fn(),
+  getServiceWidget: vi.fn(),
+  logger: {
+    debug: vi.fn(),
+  },
+}));
+
+vi.mock("utils/logger", () => ({
+  default: () => logger,
+}));
+
+vi.mock("utils/config/service-helpers", () => ({
+  default: getServiceWidget,
+}));
+
+vi.mock("utils/proxy/http", () => ({
+  httpProxy,
+}));
+
+import feedProxyHandler from "./proxy";
+
+const items = Array.from(
+  { length: 7 },
+  (_, i) => `<item><title>Item ${i}</title><link>https://example.com/${i}</link>
+    <media:thumbnail url="https://example.com/${i}.jpg" /></item>`,
+).join("");
+const feed = `<rss xmlns:media="http://search.yahoo.com/mrss/"><channel>${items}</channel></rss>`;
+
+const req = { query: { group: "g", service: "svc", index: "0" } };
+
+describe("widgets/feed/proxy", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    cache.clear();
+  });
+
+  it("returns 400 when the url is missing or invalid", async () => {
+    getServiceWidget.mockResolvedValueOnce({ type: "feed" });
+    let res = createMockRes();
+    await feedProxyHandler(req, res);
+    expect(res.statusCode).toBe(400);
+    expect(res.body).toEqual({ error: "Missing feed URL" });
+
+    getServiceWidget.mockResolvedValueOnce({ type: "feed", url: "nope" });
+    res = createMockRes();
+    await feedProxyHandler(req, res);
+    expect(res.statusCode).toBe(400);
+    expect(res.body).toEqual({ error: "Invalid feed URL" });
+
+    getServiceWidget.mockResolvedValueOnce({ type: "feed", url: "file:///etc/passwd" });
+    res = createMockRes();
+    await feedProxyHandler(req, res);
+    expect(res.statusCode).toBe(400);
+    expect(res.body).toEqual({ error: "Invalid feed URL" });
+    expect(httpProxy).not.toHaveBeenCalled();
+  });
+
+  it("returns the first 5 items by default", async () => {
+    getServiceWidget.mockResolvedValue({ type: "feed", url: "https://example.com/feed.xml" });
+    httpProxy.mockResolvedValueOnce([200, "application/rss+xml", Buffer.from(feed)]);
+
+    const res = createMockRes();
+    await feedProxyHandler(req, res);
+
+    expect(httpProxy.mock.calls[0][0].href).toBe("https://example.com/feed.xml");
+    expect(res.statusCode).toBe(200);
+    expect(res.body.items).toHaveLength(5);
+    expect(res.body.items[0]).toEqual({
+      title: "Item 0",
+      link: "https://example.com/0",
+      date: null,
+      image: "https://example.com/0.jpg",
+    });
+  });
+
+  it.each([-1, 0, "abc"])("falls back to 5 items for maxItems %j", async (maxItems) => {
+    getServiceWidget.mockResolvedValue({ type: "feed", url: "https://example.com/feed.xml", maxItems });
+    httpProxy.mockResolvedValueOnce([200, "application/rss+xml", Buffer.from(feed)]);
+
+    const res = createMockRes();
+    await feedProxyHandler(req, res);
+
+    expect(res.body.items).toHaveLength(5);
+  });
+
+  it("respects maxItems and drops images when disabled", async () => {
+    getServiceWidget.mockResolvedValue({
+      type: "feed",
+      url: "https://example.com/feed.xml",
+      maxItems: "2",
+      images: false,
+    });
+    httpProxy.mockResolvedValueOnce([200, "application/rss+xml", Buffer.from(feed)]);
+
+    const res = createMockRes();
+    await feedProxyHandler(req, res);
+
+    expect(res.body.items).toEqual([
+      { title: "Item 0", link: "https://example.com/0", date: null },
+      { title: "Item 1", link: "https://example.com/1", date: null },
+    ]);
+  });
+
+  it("passes through http errors without leaking the url", async () => {
+    getServiceWidget.mockResolvedValue({ type: "feed", url: "https://example.com/feed.xml?token=secret" });
+    httpProxy.mockResolvedValueOnce([404, "text/html", Buffer.from("Not found")]);
+
+    const res = createMockRes();
+    await feedProxyHandler(req, res);
+
+    expect(res.statusCode).toBe(404);
+    expect(res.body).toEqual({ error: { message: "HTTP Error", url: "example.com (see logs for details)" } });
+  });
+
+  it("never includes any part of the configured url in the response", async () => {
+    getServiceWidget.mockResolvedValue({
+      type: "feed",
+      url: "https://user:hunter2@nas.lan/feeds/s3cr3t/rss.xml?token=abc123",
+    });
+    const relative = `<rss><channel>
+      <item><title>Path</title><link>item/1</link><enclosure url="img.jpg" type="image/jpeg" /></item>
+      <item><title>Root</title><link>/x</link></item>
+      <item><title>Fragment</title><link>#top</link></item>
+    </channel></rss>`;
+    httpProxy.mockResolvedValueOnce([200, "application/rss+xml", Buffer.from(relative)]);
+
+    const res = createMockRes();
+    await feedProxyHandler(req, res);
+
+    expect(res.body.items.map((item) => item.link)).toEqual([null, null, null]);
+    expect(JSON.stringify(res.body)).not.toMatch(/user|hunter2|nas\.lan|s3cr3t|token|abc123/);
+  });
+
+  it("returns 500 for unparseable feeds", async () => {
+    getServiceWidget.mockResolvedValue({ type: "feed", url: "https://example.com/feed.xml" });
+    httpProxy.mockResolvedValueOnce([200, "text/html", Buffer.from("<html></html>")]);
+
+    const res = createMockRes();
+    await feedProxyHandler(req, res);
+
+    expect(res.statusCode).toBe(500);
+    expect(res.body).toEqual({ error: { message: "Invalid feed", url: "example.com (see logs for details)" } });
+  });
+
+  it("shares one cached fetch across widgets with different options", async () => {
+    getServiceWidget
+      .mockResolvedValueOnce({ type: "feed", url: "https://example.com/feed.xml", maxItems: 1 })
+      .mockResolvedValueOnce({ type: "feed", url: "https://example.com/feed.xml", images: false });
+    httpProxy.mockResolvedValue([200, "application/rss+xml", Buffer.from(feed)]);
+
+    const first = createMockRes();
+    await feedProxyHandler(req, first);
+    const second = createMockRes();
+    await feedProxyHandler(req, second);
+
+    expect(httpProxy).toHaveBeenCalledTimes(1);
+    expect(first.body.items).toHaveLength(1);
+    expect(second.body.items).toHaveLength(5);
+    expect(second.body.items[0].image).toBeUndefined();
+  });
+
+  it("does not cache failures", async () => {
+    getServiceWidget.mockResolvedValue({ type: "feed", url: "https://example.com/feed.xml" });
+    httpProxy
+      .mockResolvedValueOnce([404, "text/html", Buffer.from("Not found")])
+      .mockResolvedValueOnce([200, "application/rss+xml", Buffer.from(feed)]);
+
+    const failed = createMockRes();
+    await feedProxyHandler(req, failed);
+    const recovered = createMockRes();
+    await feedProxyHandler(req, recovered);
+
+    expect(failed.statusCode).toBe(404);
+    expect(recovered.statusCode).toBe(200);
+    expect(httpProxy).toHaveBeenCalledTimes(2);
+  });
+});

src/widgets/feed/utils.js

@@ -0,0 +1,114 @@
+import sax from "sax";
+import { xml2js } from "xml-js";
+
+const asArray = (value) => (value === undefined || value === null ? [] : [].concat(value));
+
+function getText(node) {
+  const first = asArray(node)[0];
+  if (first === undefined) return "";
+  if (typeof first !== "object") return String(first);
+  return asArray(first._cdata ?? first._text).join("");
+}
+
+export function httpUrl(value, baseUrl) {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  try {
+    const url = new URL(trimmed, baseUrl);
+    return ["http:", "https:"].includes(url.protocol) ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseDate(value) {
+  const time = Date.parse(value);
+  return Number.isNaN(time) ? null : new Date(time).toISOString();
+}
+
+const attrs = (node) => node?._attributes ?? {};
+const isImage = (node) => attrs(node).medium === "image" || attrs(node).type?.startsWith("image/");
+
+function findImage(item) {
+  const groups = [item, ...asArray(item["media:group"])];
+  const candidates = [
+    ...groups.flatMap((group) => asArray(group["media:thumbnail"])),
+    ...groups.flatMap((group) => asArray(group["media:content"])).filter(isImage),
+    ...asArray(item.enclosure).filter(isImage),
+    ...asArray(item.link).filter((link) => attrs(link).rel === "enclosure" && isImage(link)),
+  ];
+  const image = candidates.find((node) => attrs(node).url || attrs(node).href);
+  return image ? attrs(image).url || attrs(image).href : null;
+}
+
+const isPixel = ({ width, height }) => ["0", "1"].includes(width) || ["0", "1"].includes(height);
+
+// first usable <img> in item html using sax tokenizer
+function findHtmlImage(htmls, baseUrl) {
+  for (const html of htmls) {
+    if (!html) continue;
+    let image = null;
+    const parser = sax.parser(false, { lowercase: true });
+    parser.onopentag = ({ name, attributes }) => {
+      if (!image && name === "img" && !isPixel(attributes)) image = httpUrl(attributes.src, baseUrl);
+    };
+    parser.onerror = () => {
+      parser.error = null;
+      parser.resume();
+    };
+    parser.write(html).close();
+    if (image) return image;
+  }
+  return null;
+}
+
+function parseRssItem(item) {
+  const guid = asArray(item.guid)[0];
+  const guidLink = attrs(guid).isPermaLink !== "false" ? getText(guid) : null;
+  return {
+    title: getText(item.title),
+    link: getText(item.link) || guidLink,
+    date: getText(item.pubDate) || getText(item["dc:date"]),
+    image: findImage(item),
+    html: [getText(item["content:encoded"]), getText(item.description)],
+  };
+}
+
+const alternateLink = (node) => asArray(node.link).find((l) => (attrs(l).rel ?? "alternate") === "alternate");
+
+function parseAtomEntry(entry) {
+  const link = alternateLink(entry) ?? asArray(entry.link)[0];
+  return {
+    title: getText(entry.title),
+    link: attrs(link).href,
+    date: getText(entry.published) || getText(entry.updated),
+    image: findImage(entry),
+    html: [getText(entry.content), getText(entry.summary)],
+  };
+}
+
+export function parseFeed(xml) {
+  const doc = xml2js(xml, { compact: true });
+
+  let items;
+  let site;
+  if (doc.rss) {
+    items = asArray(doc.rss.channel?.item).map(parseRssItem);
+    site = getText(doc.rss.channel?.link);
+  } else if (doc.feed) {
+    items = asArray(doc.feed.entry).map(parseAtomEntry);
+    site = attrs(alternateLink(doc.feed)).href;
+  } else throw new Error("Unsupported feed format");
+
+  // resolve against the feed's own site link, never the configured url
+  const baseUrl = httpUrl(site) ?? undefined;
+
+  return items
+    .map((item) => ({
+      title: item.title.trim(),
+      link: httpUrl(item.link, baseUrl),
+      date: parseDate(item.date),
+      image: httpUrl(item.image, baseUrl) ?? findHtmlImage(item.html, baseUrl),
+    }))
+    .filter((item) => item.title);
+}

src/widgets/feed/utils.test.js

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "vitest";
+
+import { httpUrl, parseFeed } from "./utils";
+
+const rss = `<?xml version="1.0"?>
+<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:dc="http://purl.org/dc/elements/1.1/">
+  <channel>
+    <title>Example</title>
+    <link>https://example.com/</link>
+    <item>
+      <title><![CDATA[Tom & Jerry]]></title>
+      <link>https://example.com/one</link>
+      <pubDate>Tue, 22 Sep 2026 10:00:00 GMT</pubDate>
+      <media:thumbnail url="https://img.example.com/one.jpg" />
+    </item>
+    <item>
+      <title>Enclosure image</title>
+      <guid>https://example.com/two</guid>
+      <dc:date>2026-09-21T10:00:00Z</dc:date>
+      <enclosure url="/two.png" type="image/png" length="1" />
+    </item>
+    <item>
+      <title>Audio only</title>
+      <link>javascript:alert(1)</link>
+      <guid isPermaLink="false">abc-123</guid>
+      <enclosure url="https://example.com/three.mp3" type="audio/mpeg" length="1" />
+    </item>
+    <item>
+      <description>No title, skipped</description>
+    </item>
+  </channel>
+</rss>`;
+
+const atom = `<?xml version="1.0" encoding="utf-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">
+  <title>Example</title>
+  <entry>
+    <title>  Fish &amp; chips
+    </title>
+    <link rel="enclosure" type="image/jpeg" href="https://example.com/one.jpg" />
+    <link rel="alternate" href="https://example.com/one" />
+    <updated>2026-09-22T12:00:00Z</updated>
+  </entry>
+  <entry>
+    <title>YouTube style</title>
+    <link href="https://example.com/two" />
+    <published>2026-09-20T12:00:00Z</published>
+    <updated>not a date</updated>
+    <media:group>
+      <media:content url="https://example.com/two.mp4" type="video/mp4" />
+      <media:thumbnail url="https://example.com/two.jpg" />
+    </media:group>
+  </entry>
+</feed>`;
+
+describe("widgets/feed/utils", () => {
+  it("parses rss 2.0 items", () => {
+    expect(parseFeed(rss)).toEqual([
+      {
+        title: "Tom & Jerry",
+        link: "https://example.com/one",
+        date: "2026-09-22T10:00:00.000Z",
+        image: "https://img.example.com/one.jpg",
+      },
+      {
+        title: "Enclosure image",
+        link: "https://example.com/two",
+        date: "2026-09-21T10:00:00.000Z",
+        image: "https://example.com/two.png",
+      },
+      { title: "Audio only", link: null, date: null, image: null },
+    ]);
+  });
+
+  it("parses atom entries", () => {
+    expect(parseFeed(atom)).toEqual([
+      {
+        title: "Fish & chips",
+        link: "https://example.com/one",
+        date: "2026-09-22T12:00:00.000Z",
+        image: "https://example.com/one.jpg",
+      },
+      {
+        title: "YouTube style",
+        link: "https://example.com/two",
+        date: "2026-09-20T12:00:00.000Z",
+        image: "https://example.com/two.jpg",
+      },
+    ]);
+  });
+
+  it("falls back to the first usable image in item html", () => {
+    const xml = `<rss xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:media="http://search.yahoo.com/mrss/"><channel>
+      <link>https://example.com/</link>
+      <item>
+        <title>Content image</title>
+        <content:encoded><![CDATA[<p>Hi <img src="https://t.example.com/p.gif" width="1" height="1">
+          <img src="data:image/gif;base64,R0"><IMG SRC="/big.jpg?w=925&#038;h=925"><img src="/second.jpg">]]></content:encoded>
+      </item>
+      <item>
+        <title>Description image</title>
+        <description>&lt;img src="https://example.com/desc.png"&gt; unclosed &lt;b&gt;</description>
+      </item>
+      <item>
+        <title>Media wins</title>
+        <media:thumbnail url="https://example.com/thumb.jpg" />
+        <description><![CDATA[<img src="https://example.com/html.jpg">]]></description>
+      </item>
+      <item>
+        <title>No usable image</title>
+        <description><![CDATA[<img src="javascript:alert(1)"><img>]]></description>
+      </item>
+    </channel></rss>`;
+
+    expect(parseFeed(xml).map((item) => item.image)).toEqual([
+      "https://example.com/big.jpg?w=925&h=925",
+      "https://example.com/desc.png",
+      "https://example.com/thumb.jpg",
+      null,
+    ]);
+  });
+
+  it("finds images in atom html content and summary", () => {
+    const xml = `<feed xmlns="http://www.w3.org/2005/Atom">
+      <entry><title>Content</title><content type="html">&lt;img src="https://example.com/c.jpg"&gt;</content></entry>
+      <entry><title>Summary</title><summary type="html">&lt;img src="https://example.com/s.jpg"&gt;</summary></entry>
+    </feed>`;
+
+    expect(parseFeed(xml).map((item) => item.image)).toEqual([
+      "https://example.com/c.jpg",
+      "https://example.com/s.jpg",
+    ]);
+  });
+
+  it("resolves relative urls against the feed's alternate link, never its self link", () => {
+    const entry = `<entry><title>Relative</title><link href="/posts/1" /></entry>`;
+    const selfOnly = `<feed xmlns="http://www.w3.org/2005/Atom">
+      <link rel="self" href="https://example.com/user.private.atom?token=abc123" />${entry}</feed>`;
+    const withSite = `<feed xmlns="http://www.w3.org/2005/Atom">
+      <link rel="self" href="https://example.com/user.private.atom?token=abc123" />
+      <link rel="alternate" href="https://example.com/blog/" />${entry}</feed>`;
+
+    expect(parseFeed(selfOnly)[0].link).toBeNull();
+    expect(parseFeed(withSite)[0].link).toBe("https://example.com/posts/1");
+  });
+
+  it("handles single-item and empty feeds", () => {
+    const single = "<rss><channel><item><title>Only</title></item></channel></rss>";
+    expect(parseFeed(single)).toEqual([{ title: "Only", link: null, date: null, image: null }]);
+    expect(parseFeed("<feed></feed>")).toEqual([]);
+  });
+
+  it("rejects unsupported documents", () => {
+    expect(() => parseFeed("<html><body>nope</body></html>")).toThrow("Unsupported feed format");
+    expect(() => parseFeed("not xml <")).toThrow();
+  });
+
+  it.each([
+    ["https://a.com/x", undefined, "https://a.com/x"],
+    ["/x", "https://a.com/feed", "https://a.com/x"],
+    ["data:image/png;base64,AAAA", undefined, null],
+    ["not a url", undefined, null],
+    ["", undefined, null],
+    ["  \n ", "https://a.com/feed", null],
+    [" /x ", "https://a.com/feed", "https://a.com/x"],
+  ])("httpUrl(%j, %j) is %j", (value, base, expected) => {
+    expect(httpUrl(value, base)).toBe(expected);
+  });
+});

src/widgets/feed/widget.js

@@ -0,0 +1,8 @@
+import feedProxyHandler from "./proxy";
+
+const widget = {
+  api: "{url}",
+  proxyHandler: feedProxyHandler,
+};
+
+export default widget;

src/widgets/feed/widget.test.js

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+
+import { expectWidgetConfigShape } from "test-utils/widget-config";
+
+import widget from "./widget";
+
+describe("feed widget config", () => {
+  it("exports a valid widget config", () => {
+    expectWidgetConfigShape(widget);
+    expect(widget.api).toBe("{url}");
+  });
+});

src/widgets/gitea/widget.js

@@ -11,10 +11,13 @@ const widget = {
     },
     issues: {
       endpoint: "repos/issues/search",
-      map: (data) => ({
+      map: (data) => {
-        pulls: asJson(data).filter((issue) => issue.pull_request),
+        const items = asJson(data);
-        issues: asJson(data).filter((issue) => !issue.pull_request),
+        return {
-      }),
+          pulls: items.filter((issue) => issue.pull_request),
+          issues: items.filter((issue) => !issue.pull_request),
+        };
+      },
     },
     repositories: {
       endpoint: "repos/search",

src/widgets/gitea/widget.test.js

@@ -1,4 +1,4 @@
-import { describe, it } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import { expectWidgetConfigShape } from "test-utils/widget-config";
 
@@ -8,4 +8,13 @@ describe("gitea widget config", () => {
   it("exports a valid widget config", () => {
     expectWidgetConfigShape(widget);
   });
+
+  it("splits issues and pull requests", () => {
+    const result = widget.mappings.issues.map(
+      Buffer.from(JSON.stringify([{ id: 1, pull_request: {} }, { id: 2 }, { id: 3 }])),
+    );
+
+    expect(result.pulls.map((i) => i.id)).toEqual([1]);
+    expect(result.issues.map((i) => i.id)).toEqual([2, 3]);
+  });
 });

src/widgets/miniflux/widget.js

@@ -8,10 +8,13 @@ const widget = {
   mappings: {
     counters: {
       endpoint: "feeds/counters",
-      map: (data) => ({
+      map: (data) => {
-        read: Object.values(asJson(data).reads).reduce((acc, i) => acc + i, 0),
+        const { reads, unreads } = asJson(data);
-        unread: Object.values(asJson(data).unreads).reduce((acc, i) => acc + i, 0),
+        return {
-      }),
+          read: Object.values(reads).reduce((acc, i) => acc + i, 0),
+          unread: Object.values(unreads).reduce((acc, i) => acc + i, 0),
+        };
+      },
     },
   },
 };

src/widgets/miniflux/widget.test.js

@@ -1,4 +1,4 @@
-import { describe, it } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import { expectWidgetConfigShape } from "test-utils/widget-config";
 
@@ -8,4 +8,12 @@ describe("miniflux widget config", () => {
   it("exports a valid widget config", () => {
     expectWidgetConfigShape(widget);
   });
+
+  it("sums read and unread counters", () => {
+    const result = widget.mappings.counters.map(
+      Buffer.from(JSON.stringify({ reads: { 1: 2, 2: 3 }, unreads: { 1: 4, 2: 1 } })),
+    );
+
+    expect(result).toEqual({ read: 5, unread: 5 });
+  });
 });

src/widgets/radarr/widget.js

@@ -1,4 +1,4 @@
-import { asJson, jsonArrayFilter } from "utils/proxy/api-helpers";
+import { asJson } from "utils/proxy/api-helpers";
 import genericProxyHandler from "utils/proxy/handlers/generic";
 
 const widget = {
@@ -8,15 +8,18 @@ const widget = {
   mappings: {
     movie: {
       endpoint: "movie",
-      map: (data) => ({
+      map: (data) => {
-        wanted: jsonArrayFilter(data, (item) => item.monitored && !item.hasFile && item.isAvailable).length,
+        const movieData = asJson(data) ?? [];
-        have: jsonArrayFilter(data, (item) => item.hasFile).length,
+        return {
-        missing: jsonArrayFilter(data, (item) => item.monitored && !item.hasFile).length,
+          wanted: movieData.filter((item) => item.monitored && !item.hasFile && item.isAvailable).length,
-        all: asJson(data).map((entry) => ({
+          have: movieData.filter((item) => item.hasFile).length,
-          title: entry.title,
+          missing: movieData.filter((item) => item.monitored && !item.hasFile).length,
-          id: entry.id,
+          all: movieData.map((entry) => ({
-        })),
+            title: entry.title,
-      }),
+            id: entry.id,
+          })),
+        };
+      },
     },
     "queue/status": {
       endpoint: "queue/status",

src/widgets/radarr/widget.test.js

@@ -33,4 +33,27 @@ describe("radarr widget config", () => {
 
     expect(queue.map((entry) => entry.movieId)).toEqual([2, 1]);
   });
+
+  it("maps movie counts and titles", () => {
+    const movies = widget.mappings.movie.map(
+      Buffer.from(
+        JSON.stringify([
+          { id: 1, title: "A", monitored: true, hasFile: false, isAvailable: true },
+          { id: 2, title: "B", monitored: true, hasFile: true },
+          { id: 3, title: "C", monitored: true, hasFile: false, isAvailable: false },
+        ]),
+      ),
+    );
+
+    expect(movies).toEqual({
+      wanted: 1,
+      have: 1,
+      missing: 2,
+      all: [
+        { title: "A", id: 1 },
+        { title: "B", id: 2 },
+        { title: "C", id: 3 },
+      ],
+    });
+  });
 });

src/widgets/unmanic/widget.js

@@ -8,10 +8,13 @@ const widget = {
   mappings: {
     workers: {
       endpoint: "workers/status",
-      map: (data) => ({
+      map: (data) => {
-        total_workers: asJson(data).workers_status.length,
+        const workers = asJson(data).workers_status;
-        active_workers: asJson(data).workers_status.filter((worker) => !worker.idle).length,
+        return {
-      }),
+          total_workers: workers.length,
+          active_workers: workers.filter((worker) => !worker.idle).length,
+        };
+      },
     },
     pending: {
       method: "POST",

src/widgets/unmanic/widget.test.js

@@ -1,4 +1,4 @@
-import { describe, it } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import { expectWidgetConfigShape } from "test-utils/widget-config";
 
@@ -8,4 +8,12 @@ describe("unmanic widget config", () => {
   it("exports a valid widget config", () => {
     expectWidgetConfigShape(widget);
   });
+
+  it("counts total and active workers", () => {
+    const result = widget.mappings.workers.map(
+      Buffer.from(JSON.stringify({ workers_status: [{ idle: true }, { idle: false }, { idle: false }] })),
+    );
+
+    expect(result).toEqual({ total_workers: 3, active_workers: 2 });
+  });
 });

src/widgets/widgets.js

@@ -31,6 +31,7 @@ import duplicati from "./duplicati/widget";
 import emby from "./emby/widget";
 import esphome from "./esphome/widget";
 import evcc from "./evcc/widget";
+import feed from "./feed/widget";
 import filebrowser from "./filebrowser/widget";
 import fileflows from "./fileflows/widget";
 import firefly from "./firefly/widget";
@@ -191,6 +192,7 @@ const widgets = {
   emby,
   esphome,
   evcc,
+  feed,
   filebrowser,
   fileflows,
   firefly,