pmtiles-swarm 0.5.6 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,64 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.7.0
+### ✨ Features and improvements
+- **A feed can be told how long to keep what it brings in.** `keep` and `keepDays` now work on a
+  subscription, applied by the same code a watched folder and a scheduled source retire under and
+  with the same guards: only after something new has landed, and never the newest copy. A feed
+  publishing weekly leaves a copy behind every week and the publisher goes on listing all of them,
+  so `keepDays: 10` against a weekly feed keeps a fortnight and drops the rest.
+
+  This is not what `prune` does, and the difference is why a feed needed its own answer. Pruning is
+  about the publisher — it stopped offering this, so let it go — and needs a complete listing for an
+  absence to mean anything, which is why it applies to a catalogue and not to a feed.
+  planet.openstreetmap.org lists five dumps and says nothing about the hundreds before them. Age is
+  age however short the list is.
+- **Feeds and remote nodes are two sections rather than one table with a dropdown.** They are not
+  one thing in two costumes: a feed is bounded and says "here is what is new", so it caps items per
+  check and can never prune; a catalogue says "here is everything", which is the only thing that
+  makes an absence meaningful. Half the columns applied to one and half to the other. A row is now
+  RSS or API because of the table it sits in, which also means a saved row states its protocol
+  instead of leaving it to be guessed from the URL later. Rows written before this are sorted into
+  a section by the same rule the subscription manager itself uses.
+- **A feed's save path is editable.** `savePath` was accepted in the configuration and offered
+  nowhere, so it could only be set by hand — and before the row editor learned to keep fields it
+  does not show, pressing Save would have deleted it.
+
+## 0.6.0
+### ✨ Features and improvements
+- **Check now, on scheduled sources and on feeds.** A schedule describes ordinary operation, and
+  setting one up is not ordinary operation — waiting six hours to find out whether a URL template
+  is right is how a typo survives a working day. `POST /api/sources/check` is new; the feed
+  equivalent existed and had no button. Both check what is *saved* rather than what is on screen,
+  since an unsaved row is not a source this node knows about.
+- **Run the completion hook again for one archive**, from its General tab or
+  `POST /api/torrents/<infohash>/hooks/complete`. Completion is recorded before the command runs,
+  so a build taking six hours is not started six times over — but a hook that failed for a reason
+  since fixed keeps that record too, and the only way to run it again was to stop the node and
+  edit the catalog by hand. Started rather than awaited, since the command may be a planet build;
+  refused with 409 if it is already running for that archive, because two builds writing the same
+  output is worse than waiting. It does not choose *which* command — that is still the config
+  file's business, and `allowHooksFromApi` still guards choosing it.
+
+### 🐞 Bug fixes
+- **The node no longer crashes while shutting down.** `child.stdin` had no `error` listener, and
+  an unhandled `'error'` event is not a rejected promise — it is a throw that takes the process
+  with it. systemd's default `KillMode` signals every process in a service's cgroup, so the Python
+  sidecar exited first and the shutdown request was written into a dead pipe:
+
+  ```
+  [shutdown] SIGTERM
+  Error: write EPIPE ... at #call (src/engines/libtorrent.js)
+  Main process exited, code=exited, status=1/FAILURE
+  ```
+
+  Every stop ended that way, and because the crash happened *inside* `destroy()`, the shutdown
+  that saves resume data never ran — so this was also a third, independent reason resume data
+  went missing. `Restart=always` brought the node back five seconds later looking healthy, which
+  is why it went unnoticed. A failed write now fails the call that made it; the pipe is checked
+  before writing; and there is a test that spawns a sidecar which reports ready and then exits.
+
 ## 0.5.6
 ### 🐞 Bug fixes
 - **The Pieces and Peers tabs redraw themselves.** A detail pane is filled once, the first time

package/README.md

@@ -604,6 +604,8 @@ matters there is `maxConnections`, since every peer holds a NAT table entry. See
 | `POST` | `/api/sources/preview` | What a watched web location would take, without taking it |
 | `POST` | `/api/subscriptions/preview` | Whether a peer is reachable and what it offers |
 | `POST` | `/api/subscriptions/refresh` | Poll subscribed feeds now |
+| `POST` | `/api/sources/check` | Check scheduled sources now, rather than at the next due time |
+| `POST` | `/api/torrents/:infoHash/hooks/complete` | Run the completion hook again for one archive |
 | `GET` `POST` `DELETE` | `/api/tokens`, `/api/tokens/:id` | Mint, list and revoke access tokens |
 | `GET` `POST` | `/api/restart` | What a restart would do, and doing it |
 | `GET` `PATCH` | `/api/config` | Read and change settings |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.5.6",
+  "version": "0.7.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/api.js

@@ -63,6 +63,8 @@ export function createApp({
   catalog,
   engine,
   subscriptions,
+  sources,
+  hooks,
   tiles,
   warm,
   config,
@@ -1386,6 +1388,55 @@ export function createApp({
     }),
   );
 
+  // The same for scheduled sources: ask now rather than at the next due time.
+  // Worth having for the same reason a feed refresh is — a schedule is a
+  // statement about ordinary operation, and setting one up is not ordinary
+  // operation. Waiting six hours to find out whether a URL template is right
+  // is how a typo survives a working day.
+  app.post(
+    '/api/sources/check',
+    route(async (_req, res) => {
+      if (!sources?.sweep) {
+        return res.status(501).json({ error: 'no scheduled sources here' });
+      }
+      const taken = await sources.sweep(new Date());
+      res.json({ taken: taken.length, entries: taken });
+    }),
+  );
+
+  // Run the completion hook again for one archive.
+  //
+  // The sweep runs it once and records that it has, so a six-hour build is not
+  // started six times over — but a hook that failed for a reason since fixed
+  // keeps that record too, and the only way to run it again was to stop the
+  // node and edit the catalog by hand.
+  //
+  // A POST, and therefore refused to a read-only token: this runs a command as
+  // the service user. It does not choose *which* command — that is still the
+  // config file's business, and `allowHooksFromApi` still guards it.
+  app.post(
+    '/api/torrents/:infoHash/hooks/complete',
+    route(async (req, res) => {
+      if (!hooks?.runComplete) {
+        return res.status(501).json({ error: 'hooks are not available here' });
+      }
+      try {
+        const started = await hooks.runComplete(req.params.infoHash);
+        res.json({ started: true, ...started });
+      } catch (error) {
+        // Told apart because they mean different things to whoever pressed
+        // the button: nothing configured, nothing to run it for, or already
+        // going.
+        const status = /unknown archive/.test(error.message)
+          ? 404
+          : /already running/.test(error.message)
+            ? 409
+            : 400;
+        res.status(status).json({ error: error.message });
+      }
+    }),
+  );
+
   /**
    * How many items this feed request should return.
    *

package/src/config.js

@@ -555,6 +555,21 @@ const DEFAULTS = {
    * and pruning, which needs to be able to notice an absence.
    */
   subscriptions: [],
+  /*
+   * A subscription also takes `keep` and `keepDays`, which are the same rules
+   * a watched folder and a scheduled source retire under and are applied by
+   * the same code.
+   *
+   * They answer a different question from `prune`. Pruning is about the
+   * publisher — it stopped offering this, so let it go — and needs a complete
+   * listing to mean anything, which is why it applies to a catalog and not to
+   * an RSS feed. These are about the disk: a feed publishing weekly leaves a
+   * copy behind every week and goes on listing all of them, and age is age
+   * however short the list is.
+   *
+   * Retirement runs only after something new has landed, and never removes
+   * the newest copy.
+   */
   /**
    * How often to re-check whether the sources archives were built from have
    * changed, in seconds. Zero disables it. A check is one HEAD request or stat

package/src/engines/libtorrent.js

@@ -134,6 +134,24 @@ export class LibtorrentEngine {
       });
       this.#child = child;
 
+      // A pipe to a process that has gone raises 'error' on the stream, and an
+      // unhandled 'error' event is not a rejected promise — it is a throw that
+      // takes the whole node down with it. That is what happened on every
+      // stop: systemd's default KillMode signals every process in the cgroup,
+      // so the sidecar exited first and the shutdown request was written into
+      // a dead pipe. The service died with EPIPE and status=1/FAILURE, having
+      // never saved its resume data, and no `.catch()` on the call could have
+      // caught it.
+      child.stdin.on('error', (error) => {
+        if (!this.#stopping) {
+          console.warn(`[libtorrent] sidecar input failed: ${error.message}`);
+        }
+        for (const [id, waiter] of this.#pending) {
+          this.#pending.delete(id);
+          waiter.reject(error);
+        }
+      });
+
       const timer = setTimeout(() => {
         reject(
           new Error(
@@ -481,7 +499,22 @@ export class LibtorrentEngine {
         },
       });
 
-      child.stdin.write(`${JSON.stringify({ id, op, params })}\n`);
+      // Checked and reported rather than thrown at. Writing to a closed pipe
+      // is ordinary during shutdown, and a call that cannot be sent should
+      // fail as a call rather than as the process.
+      if (!child.stdin.writable || child.stdin.destroyed) {
+        this.#pending.delete(id);
+        clearTimeout(timer);
+        reject(new Error(`libtorrent ${op}: the sidecar is no longer running`));
+        return;
+      }
+
+      child.stdin.write(`${JSON.stringify({ id, op, params })}\n`, (error) => {
+        if (!error) return;
+        this.#pending.delete(id);
+        clearTimeout(timer);
+        reject(new Error(`libtorrent ${op}: ${error.message}`));
+      });
     });
   }
 

package/src/hooks.js

@@ -193,6 +193,48 @@ export class ProgramHooks {
     return fired;
   }
 
+  /**
+   * Runs the completion hook for one archive, now, whatever it did before.
+   *
+   * The sweep runs a hook once and records that it has: a build taking six
+   * hours must not be started six times over. But a hook that failed for a
+   * reason since fixed — a path that was wrong, a directory that was not
+   * writable — keeps that record too, and until now the only way to run it
+   * again was to stop the node and edit the catalog by hand.
+   *
+   * Started rather than awaited. The command may be a planet build, and a
+   * request that waited for it would time out long before it finished.
+   * @param {string} infoHash - The archive to run it for.
+   * @returns {Promise<object>} - What was started.
+   */
+  async runComplete(infoHash) {
+    if (!this.#config.onComplete?.command) {
+      throw new Error('no onComplete hook is configured');
+    }
+
+    const live = await this.#library.listWithStatus().catch(() => []);
+    const entry = live.find((candidate) => candidate.infoHash === infoHash);
+    if (!entry) throw new Error('unknown archive');
+    if (this.#running.has(infoHash)) {
+      throw new Error('it is already running for this archive');
+    }
+
+    // Recorded before starting, the same as the sweep does and for the same
+    // reason: whatever happens next, this is not a fresh completion to be
+    // picked up again a minute later.
+    await this.#library.catalog.put({
+      infoHash,
+      completedAt: new Date().toISOString(),
+    });
+
+    this.#running.add(infoHash);
+    this.#fire('onComplete', entry)
+      .catch(() => {})
+      .finally(() => this.#running.delete(infoHash));
+
+    return { name: entry.name, command: this.#config.onComplete.command };
+  }
+
   /**
    * Runs one of the configured hooks, if it is configured.
    * @param {string} which - 'onAdded' or 'onComplete'.

package/src/index.js

@@ -262,6 +262,8 @@ PMTILES_SWARM_PUBLIC_URL
     catalog,
     engine,
     subscriptions,
+    sources,
+    hooks,
     tiles,
     warm,
     config,

package/src/subscriptions.js

@@ -1,4 +1,5 @@
 import { parseFeed } from './feed.js';
+import { retains, retire } from './retention.js';
 
 /**
  * Follows other nodes' feeds and picks up what they publish.
@@ -174,6 +175,12 @@ export class SubscriptionManager {
         break;
       }
     }
+
+    // The disk side of following a feed. Pruning cannot apply here — absence
+    // from a bounded feed proves nothing — but age applies whatever the list
+    // is, which is what makes this the answer for a feed that publishes
+    // weekly for ever.
+    await this.#retire(subscription, added);
     return added;
   }
 
@@ -252,9 +259,46 @@ export class SubscriptionManager {
     }
 
     await this.#prune(subscription, document, archives);
+    await this.#retire(subscription, added);
     return added;
   }
 
+  /**
+   * Removes what this feed's archives have outgrown.
+   *
+   * Separate from pruning, and answering a different question. Pruning is
+   * about the *publisher*: it has stopped offering this, so let it go. This is
+   * about the disk: a feed publishing weekly leaves a copy behind every week,
+   * and the publisher will go on listing all of them.
+   *
+   * That distinction is why an RSS feed can have this and cannot have pruning.
+   * Absence from a bounded feed is not evidence that anything was withdrawn —
+   * planet.openstreetmap.org lists five dumps and says nothing about the
+   * hundreds before them — but age is age however short the list is.
+   *
+   * Only after something new has landed, and never the newest copy, which are
+   * the same guards a scheduled source retires under. See `retire`.
+   * @param {object} subscription - The subscription.
+   * @param {object[]} added - What this pass took, newest first.
+   * @returns {Promise<void>} - Resolves once anything due has gone.
+   */
+  async #retire(subscription, added) {
+    if (added.length === 0 || !retains(subscription)) return;
+
+    await retire({
+      library: this.#library,
+      // Only what this feed brought in. An archive built here, added by hand,
+      // or taken from another peer is not this subscription's to remove.
+      family: this.#library.catalog
+        .list()
+        .filter((entry) => entry.source?.subscription === subscription.url),
+      entry: added[0],
+      keep: subscription.keep,
+      keepDays: subscription.keepDays,
+      label: `[sync] ${subscription.url}`,
+    });
+  }
+
   /**
    * Drops archives this subscription no longer lists.
    *

package/src/web/index.html

@@ -1386,6 +1386,20 @@
                  </div>`
           }
 
+          <h2>Completion hook</h2>
+          <div class="actions" id="hook-box">
+            <button id="run-hook">Run it for this archive</button>
+            <span class="sub" id="hook-note"></span>
+          </div>
+          <div class="sub" style="margin-bottom:1rem">
+            Runs the configured <code>onComplete</code> command again for this
+            archive. It normally runs once, when the download finishes, and is
+            recorded as having run so a build taking hours is not started over
+            every minute — which also means a hook that failed for a reason
+            since fixed will not retry on its own. What it does is decided in
+            the config file; this only decides when.
+          </div>
+
           <h2>Mode</h2>
           <div class="actions" id="mode-box">
             <button id="mode-mirror">Switch to mirror</button>
@@ -1448,6 +1462,30 @@
         const loaded = new Set(['general']);
 
         /** Shows one tab, loading it the first time. */
+        const runHook = $('run-hook');
+        if (runHook) {
+          runHook.onclick = async () => {
+            const note = $('hook-note');
+            runHook.disabled = true;
+            note.textContent = 'starting…';
+            try {
+              const result = await api(
+                `/api/torrents/${infoHash}/hooks/complete`,
+                { method: 'POST' },
+              );
+              // Started, not finished: the command may be a planet build, and
+              // nothing here waits for one.
+              note.textContent = `started ${result.command ?? 'the hook'}`;
+              toast('completion hook started');
+            } catch (error) {
+              note.textContent = error.message;
+              toast(error.message);
+            } finally {
+              runHook.disabled = false;
+            }
+          };
+        }
+
         const showPane = (name) => {
           activeTab = name;
           for (const other of panel.querySelectorAll('.tabs button')) {
@@ -2363,9 +2401,32 @@
        * @returns {void}
        */
       function renderRowEditor(spec) {
-        const { into, key, title, blurb, columns, rows, restart, preview, peerPreview, footnote } =
-          spec;
+        const {
+          into,
+          key,
+          title,
+          blurb,
+          columns,
+          rows,
+          restart,
+          preview,
+          peerPreview,
+          footnote,
+          // Where to POST a "do it now". A schedule is a statement about
+          // ordinary operation, and setting one up is not ordinary operation:
+          // waiting six hours to learn whether a URL template is right is how
+          // a typo survives a working day.
+          checkNow,
+        } = spec;
         rowEditorColumns[key] = columns;
+        // Where this editor's rows belong, and what they are on top of being
+        // rows. Two editors can be two views of one array — feeds and peers
+        // are both subscriptions — so the panel's own key is a DOM name, and
+        // this is where its records are written.
+        rowEditorTargets[key] = {
+          configKey: spec.configKey ?? key,
+          stamp: spec.stamp ?? {},
+        };
         // Kept so a save can put back what this editor never showed. An entry
         // holds more than there are columns for it — a watch folder's
         // pieceLength, a subscription's savePath — and a save that rebuilt each
@@ -2380,7 +2441,9 @@
           <td>
             ${
               column.options
-                ? `<select data-field="${column.field}" style="width:${column.wide ? '17rem' : '9rem'}">
+                ? `<select data-field="${column.field}"${
+                    column.onlyFor ? ` data-only-for="${column.onlyFor}"` : ''
+                  } style="width:${column.wide ? '17rem' : '9rem'}">
                      ${column.options
                        .map(
                          ([option, label]) =>
@@ -2392,6 +2455,7 @@
                    </select>`
                 : `<input
                      data-field="${column.field}"
+                     ${column.onlyFor ? `data-only-for="${column.onlyFor}"` : ''}
                      ${column.secret ? 'type="password" autocomplete="off"' : ''}
                      placeholder="${escapeHtml(column.placeholder ?? '')}"
                      style="width:${column.wide ? '17rem' : '9rem'}"
@@ -2443,6 +2507,11 @@
           </div>
           <div style="margin-top:0.5rem">
             <button type="button" data-act="add">Add row</button>
+            ${
+              checkNow
+                ? '<button type="button" data-act="check-now">Check now</button>'
+                : ''
+            }
             <span class="sub" data-role="note"></span>
           </div>
           ${footnote ? `<div class="sub" style="margin-top:0.6rem">${escapeHtml(footnote)}</div>` : ''}`;
@@ -2450,6 +2519,40 @@
         const tbody = panel.querySelector('tbody');
         const note = panel.querySelector('[data-role="note"]');
 
+        /**
+         * Greys out the fields the chosen protocol does not read.
+         *
+         * The two halves of a subscription are not the same thing wearing
+         * different clothes. `newest` caps how many items a bounded feed hands
+         * over and means nothing to a catalog, which lists everything; `prune`
+         * needs a complete listing to make absence meaningful and so cannot
+         * apply to a feed. Offering both to both invites a setting that is
+         * quietly ignored, which is worse than not offering it.
+         *
+         * Left alone on "auto", since the protocol is then decided by the URL
+         * and this cannot know which it will be.
+         * @param {HTMLElement} row - The row to update.
+         * @returns {void}
+         */
+        const applyProtocol = (row) => {
+          const chosen = row.querySelector('[data-field="protocol"]')?.value;
+          for (const field of row.querySelectorAll('[data-only-for]')) {
+            const belongs = field.dataset.onlyFor;
+            const off = Boolean(chosen) && chosen !== belongs;
+            field.disabled = off;
+            field.title = off
+              ? `Only used by the ${belongs === 'rss' ? 'RSS' : 'catalog API'} protocol`
+              : '';
+          }
+        };
+
+        for (const row of tbody.querySelectorAll('tr')) applyProtocol(row);
+        panel.addEventListener('change', (event) => {
+          if (event.target.dataset?.field === 'protocol') {
+            applyProtocol(event.target.closest('tr'));
+          }
+        });
+
         panel.onclick = async (event) => {
           const token = event.target.dataset?.token;
           if (token) {
@@ -2475,6 +2578,29 @@
             tbody.insertAdjacentHTML('beforeend', rowHtml());
             return;
           }
+
+          if (action === 'check-now') {
+            // Against what is saved, not what is on screen. An unsaved row is
+            // not something the node knows about, and pretending otherwise
+            // would report on a source that does not exist yet.
+            const button = event.target;
+            button.disabled = true;
+            note.textContent = 'checking…';
+            try {
+              const result = await api(checkNow, { method: 'POST' });
+              const count = result.added ?? result.taken ?? 0;
+              note.textContent =
+                count > 0
+                  ? `took ${count} — save first if you have unsaved changes`
+                  : 'nothing new';
+              if (count > 0) refresh();
+            } catch (error) {
+              note.textContent = error.message;
+            } finally {
+              button.disabled = false;
+            }
+            return;
+          }
           if (action === 'drop') {
             // Never leave it with nothing to type into.
             if (tbody.children.length === 1) row.querySelectorAll('input').forEach((i) => (i.value = ''));
@@ -2581,6 +2707,7 @@
         for (const [key, columns] of Object.entries(specs)) {
           const panel = document.querySelector(`[data-row-editor="${key}"]`);
           if (!panel) continue;
+          const target = rowEditorTargets[key] ?? { configKey: key, stamp: {} };
           const originals = rowEditorRows[key] ?? [];
           const records = [...panel.querySelectorAll('tbody tr')]
             .map((row) => {
@@ -2594,8 +2721,17 @@
                 origin === undefined ? {} : (originals[Number(origin)] ?? {}),
               );
             })
-            .filter((record) => record[columns[0].field]);
-          updates[key] = records;
+            .filter((record) => record[columns[0].field])
+            // What the section says about every row in it. A row in the feeds
+            // table is an RSS subscription because of where it is, which is
+            // the point of having two tables rather than a dropdown.
+            .map((record) => ({ ...record, ...target.stamp }));
+
+          // Appended, not assigned: several editors may write one setting.
+          updates[target.configKey] = [
+            ...(updates[target.configKey] ?? []),
+            ...records,
+          ];
         }
         return updates;
       }
@@ -3087,6 +3223,7 @@
       // ── Settings ──────────────────────────────────────────────────────────
       let restartKeys = new Set();
       let rowEditorColumns = {};
+      let rowEditorTargets = {};
       // What each editor was rendered from, so a save can put back the fields
       // it never showed.
       let rowEditorRows = {};
@@ -3148,6 +3285,7 @@
         // are lists of small records, which is exactly what a torrent client
         // gives a grid for, and what a textarea full of braces is worst at.
         rowEditorColumns = {};
+        rowEditorTargets = {};
         rowEditorRows = {};
         await renderTokenEditor(body);
         renderHookEditor(body, config, restartKeys);
@@ -3319,6 +3457,7 @@
             },
           ],
           rows: config.sources ?? [],
+          checkNow: '/api/sources/check',
           preview: true,
           footnote:
             'Tokens combine however the upstream spells its filenames — ' +
@@ -3378,35 +3517,100 @@
           </div>`;
         body.append(feedGlobals);
 
+        // Which table a subscription belongs in — the same question the
+        // subscription manager asks itself: an explicit protocol decides it, and
+        // otherwise the shape of the URL does.
+        const isPeer = (row) =>
+          row.protocol === 'api' ||
+          (!row.protocol && /\/api\/catalog\/?$/.test(row.url ?? ''));
+        const following = config.subscriptions ?? [];
+
         renderRowEditor({
           into: body,
-          key: 'subscriptions',
-          title: 'Remote nodes',
+          key: 'feeds',
+          configKey: 'subscriptions',
+          // A row here is RSS because of the table it is in, which is the
+          // point of two tables rather than a dropdown nobody reads.
+          stamp: { protocol: 'rss' },
+          title: 'RSS feeds',
           blurb:
-            'Feeds this node follows: another swarm node, or any RSS feed ' +
-            'that carries torrents — planet.openstreetmap.org publishes one ' +
-            'for the planet dumps. An RSS feed says "here is what is new" ' +
-            'and is bounded by the publisher, so a node offline long enough ' +
-            'misses things for good; a catalog URL says "here is ' +
-            'everything", which is what makes reconciling possible. A token, ' +
-            'where the peer issued one, may get you more than it publishes ' +
-            'to the world.',
+            'Any feed that carries torrents — another swarm node publishes ' +
+            'one, and so does planet.openstreetmap.org for the planet dumps. ' +
+            'A feed says "here is what is new" and is bounded by whoever ' +
+            'publishes it, so a node offline long enough misses things for ' +
+            'good, and an absence from one means nothing at all.',
           columns: [
             {
               field: 'url',
-              label: 'Feed or catalog URL',
-              placeholder: 'https://peer.example.org/feed.xml',
+              label: 'Feed URL',
+              placeholder: 'https://planet.openstreetmap.org/pbf/planet-pbf-rss.xml',
               wide: true,
             },
             {
-              field: 'protocol',
-              label: 'Protocol',
+              field: 'mode',
+              label: 'Take as',
+              options: [
+                ['cache', 'cache — on demand'],
+                ['mirror', 'mirror — whole copy'],
+              ],
+            },
+            { field: 'newest', label: 'Items per check', placeholder: '1', number: true },
+            {
+              field: 'categories',
+              label: 'Categories',
+              placeholder: 'from-peer, planet',
+              list: true,
+            },
+            { field: 'filter', label: 'Name filter', placeholder: 'terrain' },
+            { field: 'savePath', label: 'Save to', placeholder: 'the default' },
+            { field: 'token', label: 'Token', placeholder: 'if issued one', secret: true },
+            { field: 'keep', label: 'Copies to keep', placeholder: 'all', number: true },
+            { field: 'keepDays', label: 'Keep for (days)', placeholder: 'for ever', number: true },
+            {
+              field: 'enabled',
+              label: 'On',
+              boolean: true,
               options: [
-                ['', 'auto'],
-                ['rss', 'RSS'],
-                ['api', 'catalog API'],
+                ['', 'yes'],
+                ['false', 'no'],
               ],
             },
+          ],
+          rows: following.filter((row) => !isPeer(row)),
+          checkNow: '/api/subscriptions/refresh',
+          peerPreview: true,
+          footnote:
+            'Items per check is 1 by default and counts from the newest, ' +
+            'because a feed listing five planet dumps is four hundred ' +
+            'gigabytes if you take the lot; 0 takes everything it lists. ' +
+            'Copies to keep and Keep for are about your disk rather than the ' +
+            'publisher: a feed publishing weekly leaves a copy behind every ' +
+            'week and goes on listing all of them. Both run only after ' +
+            'something new has landed, and neither removes the newest copy. ' +
+            'There is no dropping here — absence from a bounded feed is not ' +
+            'evidence that anything was withdrawn, which is what a catalogue ' +
+            'is for.',
+        });
+
+        renderRowEditor({
+          into: body,
+          key: 'peers',
+          configKey: 'subscriptions',
+          stamp: { protocol: 'api' },
+          title: 'Remote nodes',
+          blurb:
+            'Another swarm node, followed through its catalogue rather than ' +
+            'its feed. A catalogue says "here is everything", which is what ' +
+            'makes reconciling possible — and dropping, which needs to be ' +
+            'able to notice an absence. A token, where the peer issued one, ' +
+            'may get you more than it publishes to the world.',
+          columns: [
+            {
+              field: 'url',
+              label: 'Catalogue URL',
+              placeholder: 'https://peer.example.org/api/catalog',
+              wide: true,
+            },
             {
               field: 'mode',
               label: 'Take as',
@@ -3415,19 +3619,14 @@
                 ['mirror', 'mirror — whole copy'],
               ],
             },
-            {
-              field: 'newest',
-              label: 'Items per check',
-              placeholder: '1',
-              number: true,
-            },
             {
               field: 'categories',
               label: 'Categories',
-              placeholder: 'from-peer, planet',
+              placeholder: 'from-peer',
               list: true,
             },
             { field: 'filter', label: 'Name filter', placeholder: 'terrain' },
+            { field: 'savePath', label: 'Save to', placeholder: 'the default' },
             { field: 'token', label: 'Token', placeholder: 'if issued one', secret: true },
             {
               field: 'prune',
@@ -3439,6 +3638,8 @@
                 ['delete', 'forget and delete'],
               ],
             },
+            { field: 'keep', label: 'Copies to keep', placeholder: 'all', number: true },
+            { field: 'keepDays', label: 'Keep for (days)', placeholder: 'for ever', number: true },
             {
               field: 'enabled',
               label: 'On',
@@ -3449,7 +3650,8 @@
               ],
             },
           ],
-          rows: config.subscriptions ?? [],
+          rows: following.filter(isPeer),
+          checkNow: '/api/subscriptions/refresh',
           peerPreview: true,
           footnote:
             'Take as decides the disk this costs: cache joins the swarm and ' +
@@ -3457,10 +3659,7 @@
             'every archive the peer lists. Dropping stays off unless chosen, ' +
             'only ever considers archives this peer sent, and never acts on a ' +
             'filtered or partial view — watch a new peer on "report only" ' +
-            'before trusting it with anything more. Items per check is 1 by ' +
-            'default and counts from the newest, because a feed listing five ' +
-            'planet dumps is four hundred gigabytes if you take the lot; 0 ' +
-            'takes everything it lists.',
+            'before trusting it with anything more.',
         });
 
         for (const [key, value] of Object.entries(config)) {