Release 0.10.2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-10-05
+
+### Fixed
+
+- A publisher's correction to an item already in iPX, a retitled episode, mended text, new artwork or a fixed length, arrives on the next read. Since 0.9.1 an item kept what it first said: Ain't It Cool News's items each showed the text of the one before, long after the feed was fixed.
+- A feed's page in the Directory says when the feed is failing, and why, and no longer says nobody here subscribes to a feed someone does.
+
 ## [0.10.1] - 2026-10-05
 
 ### Fixed
@@ -751,7 +758,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Torrent enclosures through librqbit, seeding to a ratio or a time, with a stall timeout.
 - `ipx import` and `ipx export` for OPML, and systemd units in `contrib/`.
 
-[unreleased]: https://git.sdf1.net/rays/ipx/compare/v0.10.1...main
+[unreleased]: https://git.sdf1.net/rays/ipx/compare/v0.10.2...main
+[0.10.2]: https://git.sdf1.net/rays/ipx/compare/v0.10.1...v0.10.2
 [0.10.1]: https://git.sdf1.net/rays/ipx/compare/v0.10.0...v0.10.1
 [0.10.0]: https://git.sdf1.net/rays/ipx/compare/v0.9.1...v0.10.0
 [0.9.1]: https://git.sdf1.net/rays/ipx/compare/v0.9.0...v0.9.1

Cargo.lock

@@ -1820,7 +1820,7 @@ checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
 
 [[package]]
 name = "ipx"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "ammonia",
  "anyhow",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ipx"
-version = "0.10.1"
+version = "0.10.2"
 edition = "2024"
 
 [dependencies]

docs/architecture.md

@@ -38,7 +38,9 @@ build needs node and `npm ci` run once.
    re-derived into the database each scan, never written to config.toml. A Patreon creator link
    (a token, no `show=`) with more than one show is treated the same way, before any fetch: its
    shows come from Patreon's web API and each becomes a derived feed.
-4. Record entries. A changed title or description flips the item back to unread.
+4. Record entries: the new ones, and those the feed now gives a different title, text, artwork,
+   length or number, compared with what is stored for the items it lists (#141). A corrected item
+   keeps its read state.
 5. Record enclosures. `enclosures.url` is `UNIQUE`, which is the dedupe key and subsumes the
    original's `history.dat` pickle: a reaped file keeps its row so it is never fetched twice.
 6. Apply the merged policy (see [users.md](users.md)) and mark anything rejected as `skipped` with
@@ -90,13 +92,15 @@ printf '{"cmd":"fetch","force":true}\n' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/
 ```
 
 **Commands** — `fetch` (optional `feed`, `force`), `reap` (optional `dry_run`), `download`
-(`enclosure`), `status`.
+(`enclosure`), `status`, `reload` (read the catalogue and settings again from the database, which
+`ipx add`, `rm` and `import` send after changing them in a process of their own; answered with
+`status`).
 
 **Events** — `feed_start`, `feed_skip`, `feed_done`, `feed_error`, `progress`, `download_done`,
 `download_error`, `torrent_deferred`, `reaped`, `reap_done`, `scan_done`, `status`, `error`.
 `scan_done`, `reap_done` and `status` are terminal: a client that asked for work stops reading
-there. Commands run one at a time, in the order they arrive, except `status`: the socket answers it
-straight away, so the Docker healthcheck is never left waiting behind a scan or a download, and
+there. Commands run one at a time, in the order they arrive, except `status` and `reload`: the
+socket answers them straight away, so the Docker healthcheck is never left waiting behind a scan or a download, and
 answers only the client that asked, since `status` would end any other client's session.
 
 Progress carries the enclosure id, without which a UI cannot tell one download from another and
@@ -128,7 +132,7 @@ else a `401`. A feed's items and files (its entries, `download-latest`, `/api/en
 | `POST /api/enclosures/{id}/download`, `DELETE /api/enclosures/{id}` | `?force=true` overrides the shared-file warning |
 | `POST /api/fetch` | |
 | `GET /api/opml`, `POST /api/opml` | export your subscriptions; subscribe to every feed in an OPML |
-| `GET /api/directory/{id}` | a listed feed's description and latest twenty items, for its page before you subscribe: title, link, date, length and text, never a file or its address, and only for a feed the directory lists |
+| `GET /api/directory/{id}` | a listed feed's description, why its last check failed when it did (in words, never its error, which can name its address), and latest twenty items, for its page before you subscribe: title, link, date, length and text, never a file or its address, and only for a feed the directory lists |
 | `GET /api/popular`, `GET /api/directory`, `POST /api/popular/{id}` | the ten most subscribed feeds, and every listable feed A to Z, with an OPML's feeds in place of the OPML and everyone counted (id, title, art, count, whether it is yours, the feed's iTunes category, whether it carries audio or video; never a URL, never a private feed); subscribe by id |
 | `GET /api/settings`, `PATCH /api/settings` | admin-only to write |
 | `GET /api/users`, `POST /api/users`, `PATCH /api/users/{id}`, `DELETE /api/users/{id}` | admin-only; the only admin cannot be demoted or removed |

docs/cli.md

@@ -13,13 +13,17 @@ processes must never download the same thing. `--local` forces the work to happe
 | `ipx list` | Subscriptions and their state |
 | `ipx status` | Counts: feeds, pending, downloaded |
 | `ipx fetch [FEED] [--force]` | Scan everything, or one feed. `--force` ignores the TTL |
-| `ipx add <url> [--folder X] [--keywords a,b]` | Subscribe; the id comes from the feed title |
+| `ipx add <url> [--folder X] [--keywords a,b] [--list] [--category C]` | Subscribe; the id comes from the feed title. `--list` puts it in the Directory for anyone to subscribe to instead, and keeps it there when its last subscriber leaves; `--category` files it under one of the Directory's categories. Run for a feed already in the catalogue, these list it or set its category |
 | `ipx rm <feed>` | Unsubscribe; downloads and history are kept |
 | `ipx import <file.opml>` / `ipx export <file.opml>` | Move subscriptions in or out. Import subscribes the first admin, as the shared web token does; in the web UI it subscribes whoever is signed in |
 | `ipx reap [--dry-run]` | Run retention now |
 | `ipx user <add\|list\|passwd\|rm>` | Accounts for the web UI |
 | `ipx daemon [--web ADDR]` | Scheduler, control socket and web UI |
 
+`add`, `rm` and `import` change the catalogue in a process of their own. With a daemon running they
+then tell it to read the catalogue again; without that it kept its own copy and wrote it back at
+its next change, undoing them. If it does not answer they say so: restart it.
+
 ## Accounts
 
 Passwords are read from **stdin**, so they miss the shell history and any `ps` listing.

docs/configuration.md

@@ -27,6 +27,12 @@ config.toml's default location is `$XDG_CONFIG_HOME/ipx/config.toml`
 Postgres database instead. Back SQLite up by copying `state.db` while the daemon is stopped, or
 with `sqlite3 state.db .backup`; back Postgres up with `pg_dump`.
 
+ipx does not wait for the disk to confirm each write: SQLite syncs at checkpoints
+(`synchronous=NORMAL`), and ipx's own Postgres sessions set `synchronous_commit=off`, which leaves
+other databases on the server as they are. Waiting made a scan take most of a second a feed. A
+crash of ipx loses nothing; a power cut, or a crash of the Postgres server, can lose the last moment
+of changes, a read mark or a saved position, and never corrupts the database.
+
 ## `[general]`
 
 ```toml

docs/users.md

@@ -87,6 +87,10 @@ Patreon or Supercast, which put the key in the path, and any feed inside an OPML
 itself. Those are someone's paid subscriptions, and listing them would let anyone here read what
 they pay for.
 
+**Currently Listening**, under the Directory, is every episode you started and have not finished,
+across all your feeds, with how much is left. A click picks one up where you left off. The search
+box looks through it, as it does a feed's items, and through the Directory by name.
+
 An admin can do the same from **Settings → Manage users…**: add someone (with a password, or none
 for someone the proxy signs in), tick or untick Admin, or remove an account. Removing one takes its
 subscriptions and read state with it; downloaded files stay. The only admin cannot be demoted or

src/db.rs

@@ -2059,6 +2059,64 @@ impl Db {
         ))
     }
 
+    /// Of these items, the stored ones the feed now tells differently: a title, text, artwork,
+    /// length or number that is not what is stored, a field the feed leaves out counting as
+    /// unchanged, as record_entry writes them. A scan inserted only items it had not stored
+    /// (#96), and with that alone a publisher's correction never arrived: Ain't It Cool News's
+    /// items kept a broken copy, each with the text of the one before it, after the feed was
+    /// fixed (#141). Only what the feed lists is read back, so a scan reads as much as it was
+    /// sent, not the archive.
+    #[tracing::instrument(skip_all)]
+    pub async fn changed_items(
+        &self,
+        feed_id: &str,
+        entries: &[crate::feed::Entry],
+    ) -> Result<std::collections::HashSet<String>> {
+        if entries.is_empty() {
+            return Ok(Default::default());
+        }
+        let mut a = Args::default();
+        let feed = a.p(feed_id);
+        let guids: Vec<String> = entries.iter().map(|e| a.p(e.guid.clone())).collect();
+        let sql = format!(
+            "SELECT guid, title, description, image, duration, episode, season FROM entries
+              WHERE feed_id = {feed} AND guid IN ({})",
+            guids.join(", ")
+        );
+        type Stored = (Option<String>, Option<String>, Option<String>, Option<i64>, Option<i64>, Option<i64>);
+        let mut stored = std::collections::HashMap::<String, Stored>::new();
+        for r in self.rows(&sql, a.0).await? {
+            stored.insert(
+                r.try_get("", "guid")?,
+                (
+                    r.try_get("", "title")?,
+                    r.try_get("", "description")?,
+                    r.try_get("", "image")?,
+                    r.try_get("", "duration")?,
+                    r.try_get("", "episode")?,
+                    r.try_get("", "season")?,
+                ),
+            );
+        }
+        fn differs<T: PartialEq>(new: &Option<T>, old: &Option<T>) -> bool {
+            new.is_some() && new != old
+        }
+        Ok(entries
+            .iter()
+            .filter(|e| {
+                stored.get(&e.guid).is_some_and(|s| {
+                    differs(&e.title, &s.0)
+                        || differs(&e.description, &s.1)
+                        || differs(&e.image, &s.2)
+                        || differs(&e.duration, &s.3)
+                        || differs(&e.episode, &s.4)
+                        || differs(&e.season, &s.5)
+                })
+            })
+            .map(|e| e.guid.clone())
+            .collect())
+    }
+
     #[tracing::instrument(skip_all)]
     pub async fn skipped_by_filter(&self, feed_id: &str) -> Result<std::collections::HashMap<String, String>> {
         self.rows(
@@ -2396,6 +2454,31 @@ mod tests {
         assert_eq!(files, ["u1"].map(String::from).into()); // u2 is g's: left to the insert to find
     }
 
+    #[tokio::test]
+    async fn a_scan_finds_the_stored_items_the_feed_now_tells_differently() {
+        let db = Db::memory().await.unwrap();
+        let item = |guid: &str, title: &str, text: Option<&str>| crate::feed::Entry {
+            guid: guid.into(),
+            title: Some(title.into()),
+            description: text.map(str::to_owned),
+            ..Default::default()
+        };
+        db.record_entry("f", &item("a", "A", Some("the review"))).await.unwrap();
+        db.record_entry("f", &item("b", "B", Some("the next review"))).await.unwrap();
+        db.record_entry("f", &item("c", "C", Some("as it was"))).await.unwrap();
+        let changed = db
+            .changed_items("f", &[
+                item("a", "A", Some("the review, fixed")), // the text corrected
+                item("b", "B renamed", Some("the next review")), // retitled
+                item("c", "C", None), // says nothing of its text: what is stored stands
+                item("d", "D", Some("new")), // not stored: the insert's, not this
+            ])
+            .await
+            .unwrap();
+        assert_eq!(changed, ["a", "b"].map(String::from).into());
+        assert!(db.changed_items("f", &[]).await.unwrap().is_empty());
+    }
+
     #[tokio::test]
     async fn only_artwork_a_feed_names_is_fetched_for_the_page() {
         let db = Db::memory().await.unwrap();

src/main.rs

@@ -1598,13 +1598,17 @@ async fn scan_one(
     // changed nothing however often the feed was scanned.
     let skipped = ctx.db.skipped_by_filter(id).await?;
     let (known_items, known_files) = ctx.db.stored_items(id).await?;
+    let changed = ctx.db.changed_items(id, &parsed.entries).await?;
     let mut scan = Scan::default();
     // Its own span: the time a feed spends after its fetch was untraced (#96).
     let store = tracing::info_span!("store", items = parsed.entries.len());
     tracing::Instrument::instrument(async {
         for entry in &parsed.entries {
-            // Only what is not stored yet is inserted; the insert would find the rest and do nothing.
-            if !known_items.contains(&entry.guid) && ctx.db.record_entry(id, entry).await? {
+            // What is not stored yet is inserted, and what the feed has changed since is written
+            // again (#141); the rest is left alone. A correction keeps the item's read state.
+            if (!known_items.contains(&entry.guid) || changed.contains(&entry.guid))
+                && ctx.db.record_entry(id, entry).await?
+            {
                 scan.new_entries += 1;
             }
             for enc in &entry.enclosures {
@@ -2299,7 +2303,8 @@ mod tests {
         assert_eq!(urls, vec!["http://x/added-by-the-cli.xml".to_string()]);
     }
 
-    /// Answers /empty with a 200 and nothing, anything else with a feed of one item.
+    /// Answers /empty with a 200 and nothing, /fixed with a feed of one item as it should read,
+    /// anything else with the same item's text broken.
     async fn empty_or_feed_server() -> String {
         use tokio::io::{AsyncReadExt, AsyncWriteExt};
         let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
@@ -2310,9 +2315,13 @@ mod tests {
                 tokio::spawn(async move {
                     let mut buf = [0u8; 2048];
                     let n = sock.read(&mut buf).await.unwrap_or(0);
-                    let empty = String::from_utf8_lossy(&buf[..n]).starts_with("GET /empty");
-                    let body = if empty { "\n" } else {
-                        "<?xml version=\"1.0\"?><rss version=\"2.0\"><channel><title>T</title><item><title>One</title><guid>g1</guid></item></channel></rss>"
+                    let req = String::from_utf8_lossy(&buf[..n]).into_owned();
+                    let body = if req.starts_with("GET /empty") {
+                        "\n"
+                    } else if req.starts_with("GET /fixed") {
+                        "<?xml version=\"1.0\"?><rss version=\"2.0\"><channel><title>T</title><item><title>One</title><guid>g1</guid><description>As it should read.</description></item></channel></rss>"
+                    } else {
+                        "<?xml version=\"1.0\"?><rss version=\"2.0\"><channel><title>T</title><item><title>One</title><guid>g1</guid><description>Somebody else's text.</description></item></channel></rss>"
                     };
                     let resp = format!("HTTP/1.1 200 OK\r\nContent-Length: {}\r\n\r\n{body}", body.len());
                     let _ = sock.write_all(resp.as_bytes()).await;
@@ -2322,6 +2331,20 @@ mod tests {
         format!("http://{addr}")
     }
 
+    #[tokio::test]
+    async fn a_publishers_correction_reaches_an_item_already_stored() {
+        let base = empty_or_feed_server().await;
+        let ctx = Arc::new(test_ctx(config::Config::default()).await);
+        let at = |path: &str| config::Feed { url: format!("{base}{path}"), ..feed() };
+        let none = db::HttpState::default();
+        let text = || ctx.db.strings_for_test("SELECT description FROM entries WHERE feed_id = 'aicn'");
+        scan_one(&ctx, "aicn", &at("/feed"), &none, false, None).await.unwrap();
+        assert_eq!(text().await, ["Somebody else's text."]);
+        // The feed fixed, the item already stored: it was left as it was (#141).
+        scan_one(&ctx, "aicn", &at("/fixed"), &none, false, None).await.unwrap();
+        assert_eq!(text().await, ["As it should read."]);
+    }
+
     #[tokio::test]
     async fn nothing_from_a_feed_that_never_posted_is_an_error_and_from_one_that_has_is_not() {
         let base = empty_or_feed_server().await;

src/web.rs

@@ -1024,9 +1024,17 @@ struct ListedItem {
 struct Listed {
     /// What the feed says it is (#130), sanitized as its items are.
     description: Option<String>,
+    /// Why its last check failed, when it did (#142), in the words a feed's own page uses.
+    failing: Option<String>,
     items: Vec<ListedItem>,
 }
 
+/// A feed's last error as its Directory page says it: explained, or that the check failed, never
+/// the error as it stands, which can name the feed's address, and the Directory names none.
+fn failure_words(err: &str) -> String {
+    crate::feed::explain_failure(err).map_or_else(|| "Its last check failed.".to_owned(), |f| f.reason.to_owned())
+}
+
 /// A listed feed's description and latest twenty items. Only a feed the Directory lists, so a
 /// guessed id reaches nothing private, as `subscribe_popular` checks.
 async fn get_listed(
@@ -1041,6 +1049,7 @@ async fn get_listed(
     let rows = state.ctx.db.entries_in(user.id, Some(&id), crate::db::Filter::parse("all"), None, 0, 20, &order).await?;
     let mut sanitizer = feed_sanitizer();
     let description = state.ctx.db.feed_description(&id).await?.map(|d| clean_description(&mut sanitizer, &d, None));
+    let failing = state.ctx.db.feed_summary(&id).await?.last_error.as_deref().map(failure_words);
     let items = rows
         .into_iter()
         .map(|e| ListedItem {
@@ -1052,7 +1061,7 @@ async fn get_listed(
             duration: e.duration,
         })
         .collect();
-    Ok(Json(Listed { description, items }))
+    Ok(Json(Listed { description, failing, items }))
 }
 
 fn sort_name(p: &PopularRow) -> String {
@@ -1146,6 +1155,14 @@ impl IntoResponse for ApiError {
 mod tests {
     use super::*;
 
+    #[test]
+    fn a_failing_feed_says_why_in_the_directory_without_its_address() {
+        assert_eq!(failure_words("the feed's address answered with nothing at all"), "This address answers with nothing; the site may be gone.");
+        // reqwest names the URL; the Directory names none.
+        let raw = "error sending request for url (http://daily-quests.com/comic/?feed=atom): connection closed";
+        assert_eq!(failure_words(raw), "Its last check failed.");
+    }
+
     #[test]
     fn a_relative_image_resolves_against_the_post() {
         let mut b = feed_sanitizer();

web/app.css

@@ -717,6 +717,7 @@ body.scan-this .fhead [data-a=scan] .i,body.scan-any .fhead [data-a=scanall] .i,
 .show .meta{min-width:0;flex:1;display:flex;flex-direction:column;align-items:flex-start;gap:5px}
 .show h2{margin:0 0 2px;font-size:30px;line-height:1.15;font-weight:700;letter-spacing:-.02em;overflow-wrap:anywhere}
 .show .sub{margin:0;color:var(--dim);font-size:13px;font-variant-numeric:tabular-nums}
+.show .dfail{color:var(--bad)}
 .show .acts{margin-top:8px}
 .dlink{padding:0;font-size:13px;color:var(--accent);text-align:left}
 .dlink:hover{text-decoration:underline}

web/src/dialogs.ts

@@ -138,6 +138,7 @@ function drawDirectory(box=$('#directory'), focus?: string){
         // Its category's page is one click away from here.
         show.category?`<button type="button" class="dlink" data-go="${esc(show.category)}">${esc(show.subcategory||show.category)}</button>`:''}
         <p class="sub">${n?`${n} ${n===1?'person here subscribes':'people here subscribe'}`:'Nobody here subscribes yet'}</p>
+        <p class="sub dfail" id="dfail" hidden></p>
         <div class="acts"><button class="btn ico primary" data-a="sub" title="Subscribe" aria-label="Subscribe">${ICON.plus}</button></div></div></div>
       <div class="about" id="dabout" hidden><p></p><button type="button" class="dlink" aria-expanded="false" hidden>More</button></div>`
       +sec(show.podcast?'Latest episodes':'Latest posts','<div class="latest" id="dshow"><p class="hint">Loading…</p></div>');
@@ -217,6 +218,8 @@ async function fillShow(box,p){
       more.textContent=open?'Less':'More'; more.setAttribute('aria-expanded',String(open));
     };
   }
+  // A broken feed says so, or it reads as a quiet one (#142).
+  if(got.failing){ const f=$('#dfail',box); f.textContent=got.failing; f.hidden=false; }
   const items=got.items;
   list.innerHTML=items.length?items.map(e=>{
     const name=entryName(e), text=name.derived?'':plainText(e.description).slice(0,500);
@@ -224,7 +227,8 @@ async function fillShow(box,p){
     return `<article class="lep"><b>${e.link?`<a href="${esc(e.link)}" target="_blank" rel="noopener">${esc(name.text)}</a>`:esc(name.text)}</b>`
       +(text?`<p>${esc(text)}</p>`:'')
       +(when.length?`<small>${when.map(s=>`<span>${s}</span>`).join('<span class="dot"></span>')}</small>`:'')+'</article>';
-  }).join(''):`<p class="hint">Nothing read from it yet. A feed nobody here subscribes to is checked once a day.</p>`;
+  }).join(''):`<p class="hint">Nothing read from it yet.${p.subscribers||got.failing?''
+    :' A feed nobody here subscribes to is checked once a day.'}</p>`;
 }
 
 /// A category as a tile: its name, how many feeds, and the covers of its three most subscribed