@isomoes/iread 0.2.1 → 0.2.3

package/README.md

@@ -4,6 +4,10 @@ A concise, local, single-user RSS/Atom reader inspired by newsboat. Keyboard-fir
 
 There is no auth, no multi-user, no cloud sync, and no background scheduler. Refresh is always user-initiated. All data lives in a single local SQLite file — by default `~/.config/iread/iread.db` — which is the trust boundary.
 
+![iread UI](https://github.com/user-attachments/assets/ca9489c9-630f-4a67-9cd5-60c18ce3544e)
+
+📺 Watch the [v0.2.2 intro video](https://www.bilibili.com/video/BV1cmJg6SEso/) on Bilibili.
+
 ## Quick start
 
 ```sh
@@ -26,6 +30,26 @@ Options:
   -h, --help         Show this help and exit
 ```
 
+## Run with Docker
+
+Prebuilt multi-arch images (amd64 + arm64) are published to the GitHub Container Registry, so no Node.js on the host is required:
+
+```sh
+docker run -d --name iread -p 8787:8787 -v iread-data:/data ghcr.io/isomoes/iread:latest
+```
+
+Then open http://localhost:8787. The SQLite database and the auto-saved `feeds.opml` mirror live under `/data` in the container — here the named `iread-data` volume — so your subscriptions survive container upgrades.
+
+A `docker-compose.yml` is included for the same thing:
+
+```sh
+docker compose up -d
+```
+
+Build the image from the checkout instead of pulling it with `docker compose up -d --build`, or `docker build -t iread .`.
+
+`PORT` (default 8787), `DB_PATH` (default `/data/iread.db`), and `OPML_PATH` (default `/data/feeds.opml`) are configurable via `-e`/`environment:`. To store data in a host directory instead of a named volume, bind-mount it and make it writable by the image's unprivileged `node` user (uid 1000), e.g. `mkdir iread-data && sudo chown 1000:1000 iread-data` then `-v "$PWD/iread-data:/data"`.
+
 ## Features
 
 - Add a feed by URL (title resolved from feed metadata), delete a feed.
@@ -41,18 +65,61 @@ Options:
 - OPML import (bulk add) and OPML export, plus an always-current `feeds.opml` auto-saved next to the database on every change for quick sharing and backup. The auto-saved file is a one-way snapshot of the database (overwritten on every change and at startup), so use it for backup and sharing — to bring feeds in, use OPML import.
 - Light, dark, and system theme, persisted to localStorage.
 
+## Usage
+
+1. Start the app (dev or production) and open it in your browser.
+2. Add a feed by pasting its RSS or Atom URL into the add-feed form in the sidebar, or import an OPML file from the OPML menu. A `config/sample-feeds.opml` file is included for a quick start, and [`isomoes/arch-config/iread/feeds.opml`](https://github.com/isomoes/arch-config/blob/master/iread/feeds.opml) is a real-world example (the feed set isomoes actually reads) you can import directly.
+3. Select a feed or a smart view (All, Unread, Starred) in the sidebar.
+4. Navigate the article list with `j` and `k`, open an article with `Enter`, and read it in the right pane.
+5. Press `r` to refresh the current feed or `R` to refresh all feeds. Refresh fetches remote feeds; client polling only refreshes local data and never re-fetches remotely.
+6. Star with `s`, toggle read with `m`, mark a whole scope read with `A`, and search with `/`.
+7. Press `?` at any time to see the full keyboard map. Press `t` to cycle the theme.
+
+## Keyboard shortcuts
+
+Keys are case-sensitive (Shift matters). Bindings fire only when you are not typing in an input and no Ctrl, Meta, or Alt modifier is held.
+
+| Key           | Action               | Effect                                                                                                                                                                                            |
+| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `j` / Down    | Down in focused pane | Pane-contextual: move the article selection (list), the feed/view selection (sidebar), or the reader scroll down one. Stops at the end (no wrap).                                                  |
+| `k` / Up      | Up in focused pane   | As `j`, upward. Stops at the start.                                                                                                                                                               |
+| `n`           | Next unread          | Jump to the next unread item below; wrap to the first unread from the top if none below.                                                                                                          |
+| `g`           | Top                  | Pane-contextual: in the list, select the first item; in the sidebar, jump to the first feed/view; in the reader, scroll the article to the top.                                                   |
+| `G`           | Bottom               | Pane-contextual: in the list, select the last item; in the sidebar, jump to the last feed/view; in the reader, scroll the article to the bottom.                                                  |
+| `Enter` / `o` | Open / focus reader  | Render the selected item, mark it read, and move focus into the reader.                                                                                                                           |
+| `J` / `]`     | Next feed/view       | Move sidebar selection down and load its items, selecting the first one.                                                                                                                          |
+| `K` / `[`     | Previous feed/view   | Move sidebar selection up and load its items.                                                                                                                                                     |
+| `m`           | Toggle read/unread   | Flip the read state of the selected item; counts update.                                                                                                                                          |
+| `s`           | Toggle star          | Flip the starred state; in the Starred view an unstarred item leaves the list.                                                                                                                    |
+| `A`           | Mark feed/view read  | Mark the current scope read and offer an Undo toast.                                                                                                                                              |
+| `r`           | Refresh current feed | Refresh the selected feed, or the feed of the selected article in a smart view.                                                                                                                   |
+| `R`           | Refresh all feeds    | Refresh every feed and update counts on completion.                                                                                                                                               |
+| `v`           | Open original        | Open the article link in a new tab.                                                                                                                                                               |
+| `#` then N    | Open link by number  | Links in the article body are numbered inline `[N]`; press `#`, type the number, and it opens in a new tab — instantly once the number is unambiguous, otherwise `Enter` confirms; `Esc` cancels. |
+| `/`           | Focus search         | Focus and select the search input.                                                                                                                                                                |
+| `Esc`         | Contextual dismiss   | Close help, clear search, or return focus from the reader to the list.                                                                                                                            |
+| `?`           | Help overlay         | Toggle the keybinding overlay.                                                                                                                                                                    |
+| `t`           | Toggle theme         | Cycle light, dark, and system theme; persisted.                                                                                                                                                   |
+
+## Project layout
+
+- `src/shared/` shared, type-only DTOs used by both server and web.
+- `src/server/` Hono API, SQLite access, feed fetch/parse/sanitize, OPML, SSRF guard.
+- `src/web/` React app: three-pane layout, hooks, components, styles.
+- `data/` development SQLite database (gitignored); production data lives in `~/.config/iread/`.
+
 ## Requirements (development)
 
 - Node.js 24 or newer (the server uses the built-in `node:sqlite` module).
 - pnpm.
 
-## Install
+### Install
 
 ```sh
 pnpm install
 ```
 
-## Develop
+### Develop
 
 ```sh
 pnpm dev
@@ -82,50 +149,3 @@ pnpm start
 Open http://localhost:8787
 
 `PORT` (default 8787), `DB_PATH` (default `~/.config/iread/iread.db`), and `OPML_PATH` (default `feeds.opml` next to the database; set empty to disable the auto-saved mirror) are read from the environment. See `config/.env.example`.
-
-## Publish to npm
-
-`pnpm publish` runs the full build via the `prepack` hook and ships only `dist/` (server, shared types, and the prebuilt web bundle); the `iread` bin points at `dist/server/cli.js`. The web framework dependencies are devDependencies, so `npx @isomoes/iread` installs only the small server runtime set.
-
-## Usage
-
-1. Start the app (dev or production) and open it in your browser.
-2. Add a feed by pasting its RSS or Atom URL into the add-feed form in the sidebar, or import an OPML file from the OPML menu. A `config/sample-feeds.opml` file is included for a quick start.
-3. Select a feed or a smart view (All, Unread, Starred) in the sidebar.
-4. Navigate the article list with `j` and `k`, open an article with `Enter`, and read it in the right pane.
-5. Press `r` to refresh the current feed or `R` to refresh all feeds. Refresh fetches remote feeds; client polling only refreshes local data and never re-fetches remotely.
-6. Star with `s`, toggle read with `m`, mark a whole scope read with `A`, and search with `/`.
-7. Press `?` at any time to see the full keyboard map. Press `t` to cycle the theme.
-
-## Keyboard shortcuts
-
-Keys are case-sensitive (Shift matters). Bindings fire only when you are not typing in an input and no Ctrl, Meta, or Alt modifier is held.
-
-| Key | Action | Effect |
-|---|---|---|
-| `j` / Down | Next article | Move selection down one row. Stops at the last item (no wrap). |
-| `k` / Up | Previous article | Move selection up one row. Stops at the first item. |
-| `n` | Next unread | Jump to the next unread item below; wrap to the first unread from the top if none below. |
-| `g` | Top | Select the first item and scroll to the top. |
-| `G` | Bottom | Select the last item and scroll to the bottom. |
-| `Enter` / `o` | Open / focus reader | Render the selected item, mark it read, and move focus into the reader. |
-| `J` / `]` | Next feed/view | Move sidebar selection down and load its items, selecting the first one. |
-| `K` / `[` | Previous feed/view | Move sidebar selection up and load its items. |
-| `m` | Toggle read/unread | Flip the read state of the selected item; counts update. |
-| `s` | Toggle star | Flip the starred state; in the Starred view an unstarred item leaves the list. |
-| `A` | Mark feed/view read | Mark the current scope read and offer an Undo toast. |
-| `r` | Refresh current feed | Refresh the selected feed, or the feed of the selected article in a smart view. |
-| `R` | Refresh all feeds | Refresh every feed and update counts on completion. |
-| `v` | Open original | Open the article link in a new tab. |
-| `#` then N | Open link by number | Links in the article body are numbered inline `[N]`; press `#`, type the number, and it opens in a new tab — instantly once the number is unambiguous, otherwise `Enter` confirms; `Esc` cancels. |
-| `/` | Focus search | Focus and select the search input. |
-| `Esc` | Contextual dismiss | Close help, clear search, or return focus from the reader to the list. |
-| `?` | Help overlay | Toggle the keybinding overlay. |
-| `t` | Toggle theme | Cycle light, dark, and system theme; persisted. |
-
-## Project layout
-
-- `src/shared/` shared, type-only DTOs used by both server and web.
-- `src/server/` Hono API, SQLite access, feed fetch/parse/sanitize, OPML, SSRF guard.
-- `src/web/` React app: three-pane layout, hooks, components, styles.
-- `data/` development SQLite database (gitignored); production data lives in `~/.config/iread/`.

package/dist/server/cli.js

@@ -91,4 +91,3 @@ for (let i = 0; i < args.length; i++) {
 // Serve the prebuilt web bundle unless the caller explicitly set NODE_ENV.
 process.env.NODE_ENV ??= 'production';
 await import('./index.js');
-//# sourceMappingURL=cli.js.map

package/dist/server/db.js

@@ -155,4 +155,3 @@ export function totalChanges() {
     const row = db.prepare('SELECT total_changes() AS n').get();
     return row.n;
 }
-//# sourceMappingURL=db.js.map

package/dist/server/feed-service.js

@@ -212,7 +212,12 @@ const UPDATE_FEED_ON_SUCCESS = `
     last_fetched_at = ?, fetch_error = NULL
   WHERE id = ?
 `;
-async function refreshFeedRow(row) {
+// Phase 1 (async, no DB, runs concurrently across feeds): fetch + parse + sanitize.
+// Never throws — a failed fetch/parse becomes an 'error' plan so the caller's loop
+// always completes. CRITICAL (review fix #13): the new etag/last_modified are
+// carried in the plan and persisted only by applyRefresh, after a fully
+// successful parse+upsert.
+async function planRefresh(row) {
     const now = Date.now();
     try {
         const result = await fetchFeed({
@@ -220,30 +225,56 @@ async function refreshFeedRow(row) {
             etag: row.etag,
             lastModified: row.last_modified,
         });
-        if (result.kind === 'notModified') {
+        if (result.kind === 'notModified')
+            return { kind: 'notModified', now };
+        const { feedMeta, commit } = await parseAndPrepare(row.feed_url, result.xml);
+        return {
+            kind: 'ok',
+            now,
+            feedMeta,
+            commit,
+            etag: result.etag,
+            lastModified: result.lastModified,
+        };
+    }
+    catch (err) {
+        return { kind: 'error', now, message: err instanceof Error ? err.message : String(err) };
+    }
+}
+// Record a failed refresh on the feed row. Shared by the error-plan branch and the
+// catch fallback so the UPDATE + error outcome live in exactly one place.
+function recordFeedError(row, now, message) {
+    db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = ? WHERE id = ?`).run(now, message, row.id);
+    return { feed: getFeedWithCounts(row.id), newItems: 0, ok: false };
+}
+// Phase 2 (synchronous DB writes): apply one plan. Fully synchronous — it never
+// awaits — so even when called from concurrent fetch workers its writes can't
+// overlap and node:sqlite never awaits mid-transaction. Only the commit + feed-row
+// update run inside the transaction.
+function applyRefresh(row, plan) {
+    try {
+        if (plan.kind === 'notModified') {
             // 304: nothing changed. Update last_fetched_at and clear any prior error.
-            db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = NULL WHERE id = ?`).run(now, row.id);
+            db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = NULL WHERE id = ?`).run(plan.now, row.id);
             return { feed: getFeedWithCounts(row.id), newItems: 0, ok: true };
         }
-        // Parse + sanitize OUTSIDE the transaction (async, CPU work, no DB). Only the
-        // synchronous DB writes (commit) run inside the transaction so node:sqlite
-        // never awaits mid-transaction. CRITICAL (review fix #13): the new
-        // etag/last_modified are persisted only here, after a fully successful
-        // parse+upsert.
-        const { feedMeta, commit } = await parseAndPrepare(row.feed_url, result.xml);
-        const newItems = transaction(() => {
-            const inserted = commit(row.id);
-            db.prepare(UPDATE_FEED_ON_SUCCESS).run(feedMeta.title, feedMeta.siteUrl, feedMeta.description, result.etag, result.lastModified, now, row.id);
-            return inserted;
-        });
-        return { feed: getFeedWithCounts(row.id), newItems, ok: true };
+        if (plan.kind === 'ok') {
+            const newItems = transaction(() => {
+                const inserted = plan.commit(row.id);
+                db.prepare(UPDATE_FEED_ON_SUCCESS).run(plan.feedMeta.title, plan.feedMeta.siteUrl, plan.feedMeta.description, plan.etag, plan.lastModified, plan.now, row.id);
+                return inserted;
+            });
+            return { feed: getFeedWithCounts(row.id), newItems, ok: true };
+        }
+        return recordFeedError(row, plan.now, plan.message);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        db.prepare(`UPDATE feeds SET last_fetched_at = ?, fetch_error = ? WHERE id = ?`).run(now, message, row.id);
-        return { feed: getFeedWithCounts(row.id), newItems: 0, ok: false };
+        return recordFeedError(row, plan.now, err instanceof Error ? err.message : String(err));
     }
 }
+async function refreshFeedRow(row) {
+    return applyRefresh(row, await planRefresh(row));
+}
 function getFeedRow(id) {
     return queryGet(`SELECT * FROM feeds WHERE id = ?`, id);
 }
@@ -257,29 +288,54 @@ export async function refreshFeed(id) {
     syncOpmlMirror();
     return { feed: outcome.feed, newItems: outcome.newItems };
 }
-/** Refresh every feed sequentially. Never fails because one feed errored;
- *  tallies refreshed/failed/newItems and returns the full updated feed list. */
+// Max feeds fetched+parsed at once in refreshAll. Bounded so we never open
+// hundreds of sockets or buffer hundreds of 10 MB bodies simultaneously.
+const REFRESH_CONCURRENCY = 8;
+// Map items through an async worker with at most `limit` in flight, preserving
+// input order in the result. Used to overlap the per-feed fetch/parse/apply work.
+async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, () => (async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await worker(items[i], i);
+        }
+    })());
+    await Promise.all(runners);
+    return results;
+}
+/** Refresh every feed. Each feed's fetch + parse runs concurrently (bounded by
+ *  REFRESH_CONCURRENCY) and its synchronous apply runs in the same worker, so the
+ *  DB writes serialize naturally and only ~concurrency feeds' parsed content is held
+ *  at once. Never fails because one feed errored; tallies refreshed/failed/newItems
+ *  and returns the full updated list. */
 export async function refreshAll() {
     const rows = queryAll(`SELECT * FROM feeds ORDER BY id ASC`);
     let refreshed = 0;
     let failed = 0;
     let newItems = 0;
-    // Sequential, one transaction per feed (commit per feed keeps each transaction
-    // short on the synchronous DB; one failure never aborts the loop).
-    for (const row of rows) {
+    // Each worker fetches+parses (concurrent) then applies its own plan (synchronous,
+    // so applies never overlap and node:sqlite stays happy). The try/catch guarantees
+    // the batch always completes: even if applyRefresh's own error path throws (a
+    // DB-level fault), that feed is tallied as failed rather than aborting the request.
+    const outcomes = await mapWithConcurrency(rows, REFRESH_CONCURRENCY, async (row) => {
         try {
-            const outcome = await refreshFeedRow(row);
-            if (outcome.ok)
-                refreshed += 1;
-            else
-                failed += 1;
-            newItems += outcome.newItems;
+            const outcome = applyRefresh(row, await planRefresh(row));
+            return { ok: outcome.ok, newItems: outcome.newItems };
         }
         catch {
-            // refreshFeedRow already records its own errors; this guards against any
-            // unexpected throw so the loop always completes.
-            failed += 1;
+            return { ok: false, newItems: 0 };
         }
+    });
+    for (const outcome of outcomes) {
+        if (outcome.ok)
+            refreshed += 1;
+        else
+            failed += 1;
+        newItems += outcome.newItems;
     }
     syncOpmlMirror();
     return { feeds: listFeeds().feeds, refreshed, failed, newItems };
@@ -529,4 +585,3 @@ export function listFeedsForExport() {
 export function syncOpmlMirror() {
     writeOpmlSnapshot(listFeedsForExport());
 }
-//# sourceMappingURL=feed-service.js.map

package/dist/server/fetch-feed.js

@@ -80,4 +80,3 @@ export async function fetchFeed(input) {
         clearTimeout(timer);
     }
 }
-//# sourceMappingURL=fetch-feed.js.map

package/dist/server/index.js

@@ -61,4 +61,3 @@ serve({ fetch: app.fetch, port: PORT }, (info) => {
     console.log(`[iread] listening on ${url}`);
 });
 export { app };
-//# sourceMappingURL=index.js.map

package/dist/server/opml-sync.js

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { dbPath } from './db.js';
 import { exportOpml } from './opml.js';
@@ -11,11 +11,24 @@ function resolveMirrorPath() {
     return join(dirname(dbPath), 'feeds.opml');
 }
 export const opmlMirrorPath = resolveMirrorPath();
+function withoutDateCreated(xml) {
+    return xml.replace(/[ \t]*<dateCreated>.*?<\/dateCreated>\r?\n?/, '');
+}
 export function writeOpmlSnapshot(feeds) {
     if (!opmlMirrorPath)
         return;
     try {
         const xml = exportOpml(feeds);
+        let existing = null;
+        try {
+            existing = readFileSync(opmlMirrorPath, 'utf-8');
+        }
+        catch {
+            existing = null;
+        }
+        if (existing !== null && withoutDateCreated(existing) === withoutDateCreated(xml)) {
+            return;
+        }
         mkdirSync(dirname(opmlMirrorPath), { recursive: true });
         const tmp = `${opmlMirrorPath}.tmp`;
         writeFileSync(tmp, xml, 'utf-8');
@@ -26,4 +39,3 @@ export function writeOpmlSnapshot(feeds) {
         console.warn(`[iread] could not write OPML mirror at ${opmlMirrorPath}: ${message}`);
     }
 }
-//# sourceMappingURL=opml-sync.js.map

package/dist/server/opml.js

@@ -135,4 +135,3 @@ export function exportOpml(feeds) {
     lines.push('');
     return lines.join('\n');
 }
-//# sourceMappingURL=opml.js.map

package/dist/server/routes/feeds.js

@@ -65,4 +65,3 @@ feeds.delete('/:id', (c) => {
         return serviceErrorToResponse(c, err);
     }
 });
-//# sourceMappingURL=feeds.js.map

package/dist/server/routes/helpers.js

@@ -41,4 +41,3 @@ export function parseOptionalInt(raw) {
     const n = Number(raw);
     return Number.isFinite(n) ? Math.trunc(n) : undefined;
 }
-//# sourceMappingURL=helpers.js.map

package/dist/server/routes/items.js

@@ -92,4 +92,3 @@ items.patch('/:id', async (c) => {
         return serviceErrorToResponse(c, err);
     }
 });
-//# sourceMappingURL=items.js.map

package/dist/server/routes/opml.js

@@ -47,4 +47,3 @@ opml.post('/', async (c) => {
     const body = result;
     return c.json(body, 200);
 });
-//# sourceMappingURL=opml.js.map

package/dist/server/sanitize.js

@@ -72,4 +72,3 @@ export function sanitizeArticleHtml(raw) {
 export function toPlainText(raw) {
     return sanitizeHtml(raw, { allowedTags: [], allowedAttributes: {} });
 }
-//# sourceMappingURL=sanitize.js.map

package/dist/server/ssrf.js

@@ -272,4 +272,3 @@ export async function fetchWithGuardedRedirects(initialUrl, init) {
     }
     throw new SsrfError(`Too many redirects (> ${MAX_REDIRECTS}).`);
 }
-//# sourceMappingURL=ssrf.js.map

package/dist/shared/types.js

@@ -2,4 +2,3 @@
 // Shared between the Hono server and the React client. Type-only (no runtime code).
 // Timestamps are Unix epoch milliseconds. Import everywhere with `import type`.
 export {};
-//# sourceMappingURL=types.js.map