feat/freshrss-reader #6

Merged
CodyWan-Kenobi merged 0 commits from refs/pull/6/head into main 2026-05-16 23:34:38 +00:00
CodyWan-Kenobi commented 2026-05-16 07:36:41 +00:00 (Migrated from codeberg.org)

Summary

Expands the FreshRSS widget from a "counts only" display into a full interactive reader. Users can browse unread articles by category (or all-unread/starred), expand articles inline to read sanitized HTML content, mark items read/unread, star/unstar, and bulk-mark a stream as read — all without leaving the dashboard.

The compact header (FreshRSS unread count) variant continues to work via the existing, untouched /api/freshrss/unread route and shares the same widget configuration.

What's new

Server (server/src/services/freshrss.service.ts + server/src/routes/api.routes.ts)

Method Path Description
POST /api/freshrss/items Stream contents with continuation; supports xt=read to filter
POST /api/freshrss/categories Joined view of subscriptions + unread counts (cheap polling target)
POST /api/freshrss/mark action: read | unread | star | unstar for one or many items
POST /api/freshrss/mark-all-read Bulk mark for a stream (reading-list, label/<name>, feed/<id>)

All routes share a FreshRSSConfig = { freshrssUrl, username, apiPassword } body shape (matches the existing /freshrss/unread route). The service module caches the ClientLogin auth token and the short-lived write token per (url, user) and auto-refreshes on 401. The existing /freshrss/unread route is refactored to use the service; its response shape is unchanged so the compact header widget keeps working.

Client (client/src/components/widgets/FreshRSSWidget.tsx + new FreshRSSArticle.tsx)

  • View selector: All Unread / any category / Starred
  • Article list paginated 20 at a time with a Load more button
  • Expand a row to reveal sanitized HTML body, mark-read/unread toggle, star/unstar toggle, and "Open original"
  • Auto-mark-as-read on expand (1 s delay, optimistic UI; reverts on error)
  • Bulk "mark all as read" for the current stream (disabled in Starred view)
  • 60 s polling refreshes only category counts; items refetch on view change, refresh button, or mark-all-read

HTML is sanitized with isomorphic-dompurify (new client dep). Allowed attributes are restricted; links are forced to target="_blank" rel="noopener noreferrer".

Compatibility

  • App.tsx widget map, WidgetConfigModal form, TabbedWidget, and Header.tsx (compact variant) are all unchanged.
  • Existing FreshRSS widget configs (URL/username/apiPassword) are honored as-is.
  • The compact header widget continues to hit /api/freshrss/unread and shows total unread.

Testing

Tested end-to-end against a FreshRSS 1.28.1 instance with ~1,170 unread items across 4 categories:

  • All five endpoints return the expected shapes
  • Round-trip mark-read → mark-unread reflects in FreshRSS web UI and in the widget counts
  • Star toggle reflects in the FreshRSS web UI's Favourites view
  • Mark-all-read zeroes the visible badge for the current view
  • Auto-refresh keeps counts in sync without an item refetch (cheap)
  • 401 on either the auth token or write token triggers a single transparent refresh

Build verification: docker compose build produces the production image cleanly; tsc reports no new type errors. Pre-existing TypeScript errors in unrelated upstream files (docker.service.ts, system.service.ts, auth.routes.ts) are not introduced or worsened by this change.

Notes for review

  • The widget keeps the same registry name (FreshRSS) and props so layout and per-user widget configs migrate without changes.
  • Auto-mark-read-on-expand defaults to ON. Open to making it a per-widget config field if preferred.
  • Token cache is process-local and resets on server restart. ClientLogin is cheap, so no persistence needed.
  • I left the existing /freshrss/unread route in place to avoid breaking the compact header widget — could be removed in a follow-up if /freshrss/categories is preferred everywhere (categories.total matches).
## Summary Expands the FreshRSS widget from a "counts only" display into a full interactive reader. Users can browse unread articles by category (or all-unread/starred), expand articles inline to read sanitized HTML content, mark items read/unread, star/unstar, and bulk-mark a stream as read — all without leaving the dashboard. The compact header (FreshRSS unread count) variant continues to work via the existing, untouched `/api/freshrss/unread` route and shares the same widget configuration. ## What's new **Server** (`server/src/services/freshrss.service.ts` + `server/src/routes/api.routes.ts`) | Method | Path | Description | |---|---|---| | POST | `/api/freshrss/items` | Stream contents with continuation; supports `xt=read` to filter | | POST | `/api/freshrss/categories` | Joined view of subscriptions + unread counts (cheap polling target) | | POST | `/api/freshrss/mark` | `action: read \| unread \| star \| unstar` for one or many items | | POST | `/api/freshrss/mark-all-read` | Bulk mark for a stream (`reading-list`, `label/<name>`, `feed/<id>`) | All routes share a `FreshRSSConfig = { freshrssUrl, username, apiPassword }` body shape (matches the existing `/freshrss/unread` route). The service module caches the `ClientLogin` auth token and the short-lived write token per `(url, user)` and auto-refreshes on 401. The existing `/freshrss/unread` route is refactored to use the service; its response shape is unchanged so the compact header widget keeps working. **Client** (`client/src/components/widgets/FreshRSSWidget.tsx` + new `FreshRSSArticle.tsx`) - View selector: All Unread / any category / Starred - Article list paginated 20 at a time with a Load more button - Expand a row to reveal sanitized HTML body, mark-read/unread toggle, star/unstar toggle, and "Open original" - Auto-mark-as-read on expand (1 s delay, optimistic UI; reverts on error) - Bulk "mark all as read" for the current stream (disabled in Starred view) - 60 s polling refreshes only category counts; items refetch on view change, refresh button, or mark-all-read HTML is sanitized with `isomorphic-dompurify` (new client dep). Allowed attributes are restricted; links are forced to `target="_blank" rel="noopener noreferrer"`. ## Compatibility - `App.tsx` widget map, `WidgetConfigModal` form, `TabbedWidget`, and `Header.tsx` (compact variant) are all unchanged. - Existing FreshRSS widget configs (URL/username/apiPassword) are honored as-is. - The compact header widget continues to hit `/api/freshrss/unread` and shows total unread. ## Testing Tested end-to-end against a FreshRSS 1.28.1 instance with ~1,170 unread items across 4 categories: - All five endpoints return the expected shapes - Round-trip mark-read → mark-unread reflects in FreshRSS web UI and in the widget counts - Star toggle reflects in the FreshRSS web UI's Favourites view - Mark-all-read zeroes the visible badge for the current view - Auto-refresh keeps counts in sync without an item refetch (cheap) - 401 on either the auth token or write token triggers a single transparent refresh Build verification: `docker compose build` produces the production image cleanly; `tsc` reports no new type errors. Pre-existing TypeScript errors in unrelated upstream files (`docker.service.ts`, `system.service.ts`, `auth.routes.ts`) are not introduced or worsened by this change. ## Notes for review - The widget keeps the same registry name (`FreshRSS`) and props so layout and per-user widget configs migrate without changes. - Auto-mark-read-on-expand defaults to ON. Open to making it a per-widget config field if preferred. - Token cache is process-local and resets on server restart. ClientLogin is cheap, so no persistence needed. - I left the existing `/freshrss/unread` route in place to avoid breaking the compact header widget — could be removed in a follow-up if `/freshrss/categories` is preferred everywhere (`categories.total` matches).
thelinuxcast commented 2026-05-16 20:28:17 +00:00 (Migrated from codeberg.org)
  1. Wrong DOMPurify package (fix requested)

isomorphic-dompurify is for SSR (it bundles jsdom). This is a pure browser component — look at what it drags in: jsdom, cssstyle,
@asamuzakjp/css-color, @asamuzakjp/dom-selector, data-urls, html-encoding-sniffer, decimal.js, etc. The lockfile grows
substantially for something that's never needed at runtime in a Vite/browser build.

Should be just dompurify (and @types/dompurify as a dev dep). Drop-in replacement for the import — DOMPurify's browser build is
~50KB vs hundreds of KB of jsdom polyfills.

  1. Auto-mark-read has no delay (discrepancy from PR description)

The description says "1 s delay, optimistic UI; reverts on error" but the actual code in handleExpand is immediate with no
setTimeout:
if (willExpand && !item.isRead) {
setItemRead(item, true); // no delay
}
Not necessarily wrong, but worth clarifying intent — an accidental click will immediately mark the item read and you'd have to
manually unmark it.

  1. /api/freshrss/categories fetches subscriptions every 60s poll

loadCategories() hits /api/freshrss/categories which does two upstream calls: fetchUnreadCount + fetchSubscriptions. Subscriptions
rarely change — this doubles the API traffic on every poll. The subscription list could be fetched once on load, or the polling
endpoint could hit /freshrss/unread (which already exists) instead.

  1. Minor: DOMPurify doesn't force target="_blank" on links

DOMPurify.sanitize(html, {
ALLOWED_ATTR: ['href', 'src', 'alt', 'title', 'target', 'rel', ...],
ADD_ATTR: ['target', 'rel'],
});

ADD_ATTR allows these attributes through, it doesn't add them. Links in article HTML that don't already have target="_blank" will
open in the current tab. Not a security issue, just a UX one. Fix with a post-sanitize hook or dangerouslySetInnerHTML wrapper that
patches tags.

  1. Minor: continuation in loadItems useCallback deps

continuation is captured in the closure but only used when append = true. This causes loadItems to be recreated every time a page
is loaded (since continuation changes). Harmless in practice but slightly wasteful — passing continuation as a parameter would be
cleaner.

1. Wrong DOMPurify package (fix requested) isomorphic-dompurify is for SSR (it bundles jsdom). This is a pure browser component — look at what it drags in: jsdom, cssstyle, @asamuzakjp/css-color, @asamuzakjp/dom-selector, data-urls, html-encoding-sniffer, decimal.js, etc. The lockfile grows substantially for something that's never needed at runtime in a Vite/browser build. Should be just dompurify (and @types/dompurify as a dev dep). Drop-in replacement for the import — DOMPurify's browser build is ~50KB vs hundreds of KB of jsdom polyfills. 2. Auto-mark-read has no delay (discrepancy from PR description) The description says "1 s delay, optimistic UI; reverts on error" but the actual code in handleExpand is immediate with no setTimeout: if (willExpand && !item.isRead) { setItemRead(item, true); // no delay } Not necessarily wrong, but worth clarifying intent — an accidental click will immediately mark the item read and you'd have to manually unmark it. 3. /api/freshrss/categories fetches subscriptions every 60s poll loadCategories() hits /api/freshrss/categories which does two upstream calls: fetchUnreadCount + fetchSubscriptions. Subscriptions rarely change — this doubles the API traffic on every poll. The subscription list could be fetched once on load, or the polling endpoint could hit /freshrss/unread (which already exists) instead. 4. Minor: DOMPurify doesn't force target="_blank" on links DOMPurify.sanitize(html, { ALLOWED_ATTR: ['href', 'src', 'alt', 'title', 'target', 'rel', ...], ADD_ATTR: ['target', 'rel'], }); ADD_ATTR allows these attributes through, it doesn't add them. Links in article HTML that don't already have target="_blank" will open in the current tab. Not a security issue, just a UX one. Fix with a post-sanitize hook or dangerouslySetInnerHTML wrapper that patches <a> tags. 5. Minor: continuation in loadItems useCallback deps continuation is captured in the closure but only used when append = true. This causes loadItems to be recreated every time a page is loaded (since continuation changes). Harmless in practice but slightly wasteful — passing continuation as a parameter would be cleaner.
CodyWan-Kenobi commented 2026-05-16 22:13:02 +00:00 (Migrated from codeberg.org)

May-16-2026-06-11-32-PM

![May-16-2026-06-11-32-PM](/attachments/5da93171-91d7-4ee2-8108-646d7a6db097)
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
thelinuxcast/Homepage!6
No description provided.