pmtiles-swarm 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -58,6 +58,14 @@
   `/api/categories`, filtered by the same `feedCategories` rule, so it can show nothing that was
   not already published — and it is not the console, which stays on the admin port.
   `publicIndex: false` turns it off, withdrawing the three paths it needs with it.
+- **`GET /latest/` lists the categories, without a credential.** Everything else under
+  `/latest/` is public — the TileJSON, the torrent, the magnet, the per-category feed — so the
+  index of what it offers belongs beside them rather than behind the console's door. The public
+  front page now leads with categories rather than only listing archives, which is the more
+  useful handle for a visitor: an archive URL names one build and goes stale on the next, while a
+  category names whichever is current. Same builder as `/api/categories`, so the two cannot drift
+  apart. The page's footer and its noscript block no longer link `/api/` paths that answer 401 to
+  exactly the audience they are shown to.
 - **The feed carries the BEP 46 identity.** `<pmtiles:mutable>` holds the magnet naming an
   archive's publishing key, so a consumer following a category across rebuilds can read the
   public key straight out of the feed instead of fetching a TileJSON to find it — the key rides

package/docs/serving-tiles.md

@@ -41,6 +41,27 @@ swarm on every attempt, doing work that could never succeed.
 
 See [internals.md](internals.md#serving-an-mbtiles-archive).
 
+## The category index
+
+`GET /latest/` lists every category this node publishes, with the endpoints
+that resolve to each one's newest build — the TileJSON, the `.torrent`, the
+magnet, the per-category feed, and the style URL with the magnet in its
+fragment.
+
+Public, and deliberately so. Everything else under `/latest/` is — the
+TileJSON, the torrent, the magnet, the feed — so the index of what `/latest/`
+offers belongs beside them rather than behind the console's door.
+`/api/categories` returns the identical list from the identical builder, and is
+guarded only because everything under `/api/` is.
+
+A category is also the handle worth publishing. An archive URL names one build
+and goes stale on the next; a category names whichever is current, so a style
+pointing at one keeps working across rebuilds.
+
+Filtered by `feedCategories` and by whatever token was presented, the same as
+the catalogue and the feeds — so it can show nothing this node was not already
+publishing.
+
 ## Missing tiles
 
 A tile the archive does not hold answers **404 for raster and 204 for vector**,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.21.0",
+  "version": "0.22.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

@@ -1744,9 +1744,19 @@ export function createApp({
   // what makes a tile immutable, but leaves nothing for a style to point at
   // that survives a rebuild — and until now the endpoints that give you one
   // were documented rather than discoverable.
-  app.get(
-    '/api/categories',
-    route(async (req, res) => {
+  /**
+   * Every category, with the endpoints that resolve to its newest build.
+   *
+   * Shared by the guarded `/api/categories` and the public `/latest/`, which
+   * want exactly the same answer — one is the console asking and the other is
+   * a stranger, and neither is told anything the other is not. Filtering runs
+   * through `publishesEntry`, so `feedCategories` and whatever token was
+   * presented decide what appears, the same as everywhere else.
+   * @param {import('express').Request} req - The request, for its credential and base URL.
+   * @returns {object[]} - One row per category, sorted by name.
+   */
+  const describeCategories = (req) => {
+    {
       const base = baseUrl(req);
       const visible = catalog
         .list()
@@ -1759,51 +1769,82 @@ export function createApp({
         }
       }
 
-      res.json(
-        [...counts.keys()].sort().map((category) => {
-          const newest = newestIn(category, req);
-          // Only PMTiles has tiles to serve, so a category whose newest build
-          // is an MBTiles archive gets a feed and a torrent but no tile
-          // endpoint — the same rule as an individual archive.
-          const servable =
-            Boolean(newest?.pmtiles) &&
-            (newest.kind ?? 'pmtiles') === 'pmtiles';
-
-          return {
-            category,
-            archives: counts.get(category),
-            newest: newest && {
-              infoHash: newest.infoHash,
-              name: newest.name,
-              size: newest.size,
-              createdAt: newest.createdAt,
-              kind: newest.kind ?? 'pmtiles',
-            },
-            servable,
-            endpoints: {
-              tileJson: servable
-                ? `${base}/latest/${category}/tiles.json`
-                : null,
-              // The same URL with a magnet in the fragment, which is what a
-              // style should carry. A fragment is never sent in a request, so
-              // an ordinary client fetches the TileJSON and ignores it, while
-              // a swarm-aware one has the magnet before it makes any call --
-              // and can therefore still start when this server cannot answer.
-              //
-              // The mutable magnet where there is one, because a category is
-              // precisely where an infohash goes stale: it names the category
-              // and resolves the current build over the DHT. Otherwise the
-              // newest build's own magnet, which pins that build but still
-              // beats a blank map when the fallback is needed at all.
-              styleUrl: servable ? styleUrlFor(category, newest, base) : null,
-              torrent: `${base}/latest/${category}/archive.torrent`,
-              magnet: `${base}/latest/${category}/magnet`,
-              feed: `${base}/feed/${category}.xml`,
-              latestFeed: `${base}/latest/${category}.xml`,
-            },
-          };
-        }),
-      );
+      return [...counts.keys()].sort().map((category) => {
+        const newest = newestIn(category, req);
+        // Only PMTiles has tiles to serve, so a category whose newest build
+        // is an MBTiles archive gets a feed and a torrent but no tile
+        // endpoint — the same rule as an individual archive.
+        const servable =
+          Boolean(newest?.pmtiles) && (newest.kind ?? 'pmtiles') === 'pmtiles';
+
+        return {
+          category,
+          archives: counts.get(category),
+          newest: newest && {
+            infoHash: newest.infoHash,
+            name: newest.name,
+            size: newest.size,
+            createdAt: newest.createdAt,
+            kind: newest.kind ?? 'pmtiles',
+          },
+          servable,
+          endpoints: {
+            tileJson: servable ? `${base}/latest/${category}/tiles.json` : null,
+            // The same URL with a magnet in the fragment, which is what a
+            // style should carry. A fragment is never sent in a request, so
+            // an ordinary client fetches the TileJSON and ignores it, while
+            // a swarm-aware one has the magnet before it makes any call --
+            // and can therefore still start when this server cannot answer.
+            //
+            // The mutable magnet where there is one, because a category is
+            // precisely where an infohash goes stale: it names the category
+            // and resolves the current build over the DHT. Otherwise the
+            // newest build's own magnet, which pins that build but still
+            // beats a blank map when the fallback is needed at all.
+            styleUrl: servable ? styleUrlFor(category, newest, base) : null,
+            torrent: `${base}/latest/${category}/archive.torrent`,
+            magnet: `${base}/latest/${category}/magnet`,
+            feed: `${base}/feed/${category}.xml`,
+            latestFeed: `${base}/latest/${category}.xml`,
+          },
+        };
+      });
+    }
+  };
+
+  // The console's view. Identical to the public one below, and guarded only
+  // because everything under /api/ is.
+  app.get(
+    '/api/categories',
+    route(async (req, res) => {
+      res.json(describeCategories(req));
+    }),
+  );
+
+  // The same list, without a credential.
+  //
+  // Everything under /latest/ is public already — the TileJSON, the torrent,
+  // the magnet, the per-category feed — so the index of what /latest/ offers
+  // belongs here rather than behind the console's door. A category is also the
+  // handle a person actually wants: an infohash names one build, and this
+  // names whichever is current, so a style pointing at it keeps working across
+  // rebuilds.
+  //
+  // Not a second implementation. It is the same builder, filtered by the same
+  // rule, so the two cannot drift into disagreeing about what is published.
+  app.get(
+    '/latest/',
+    route(async (req, res) => {
+      res.setHeader('access-control-allow-origin', '*');
+      // Short, because the answer changes when a build lands.
+      res.setHeader('cache-control', 'public, max-age=60');
+      res.json({
+        // Named so a consumer can refuse a document it does not understand,
+        // the same as the catalogue does.
+        format: 'pmtiles-swarm-categories/1',
+        generatedAt: new Date().toISOString(),
+        categories: describeCategories(req),
+      });
     }),
   );
 

package/src/web/public.html

@@ -3,10 +3,14 @@
   The public front door, served at / on the public listener when the console
   has an admin port of its own.
 
-  Reads /api/catalog and /api/categories, both of which are already public and
-  already filtered by feedCategories — so this page shows exactly what this node
-  publishes and cannot show anything else. It is deliberately plain: no build
-  step, no dependencies, and it degrades to a readable list of links if the
+  Reads /latest/ for the categories and, for the archives, /api/catalog where a
+  credential allows it and /feed.xml where one does not — everything under /api/
+  is guarded on a node with any authentication configured, which is most of them,
+  and a front page that answers 401 to its own audience is worse than none.
+
+  All three are filtered by feedCategories, so this page shows exactly what the
+  node publishes and cannot show anything else. It is deliberately plain: no
+  build step, no dependencies, and it degrades to a readable list of links if the
   script does not run.
 -->
 <html lang="en">
@@ -167,7 +171,7 @@
       <noscript>
         <p class="failed">
           This page lists the archives using JavaScript. Without it, the same
-          information is at <a href="/api/catalog">/api/catalog</a> as JSON and
+          information is at <a href="/latest/">/latest/</a> as JSON and
           <a href="/feed.xml">/feed.xml</a> as RSS.
         </p>
       </noscript>
@@ -176,8 +180,7 @@
       <div id="archives"><p class="empty">Loading…</p></div>
 
       <footer>
-        <a href="/api/catalog">catalog JSON</a> ·
-        <a href="/api/categories">categories JSON</a> ·
+        <a href="/latest/">categories JSON</a> ·
         <a href="/feed.xml">RSS feed</a> ·
         <a href="/health">health</a>
       </footer>
@@ -280,27 +283,85 @@
 
       // Categories are the handle that survives a rebuild, so they go first —
       // a style should point at one of these rather than at an infohash.
+      // Categories first, and given the same weight as an archive, because
+      // for most visitors they are the more useful thing: an archive URL names
+      // one build and goes stale on the next, while a category names whichever
+      // is current and keeps working across rebuilds. A style should point at
+      // one of these.
       const renderCategories = (categories) => {
         const host = document.getElementById('categories');
-        const usable = categories.filter((c) => c.endpoints?.styleUrl);
+        host.textContent = '';
+        const usable = categories.filter((c) => c.endpoints);
         if (usable.length === 0) return;
 
         host.append(el('h2', null, 'Categories'));
-        const urls = el('div', 'urls');
+        host.append(
+          el(
+            'p',
+            'facts',
+            'These follow the newest build. Point a style at one of these ' +
+              'rather than at an archive below, and it keeps working when the ' +
+              'archive is rebuilt.',
+          ),
+        );
+
         for (const entry of usable) {
-          // `category` and `archives` are what /api/categories actually calls
+          // `category` and `archives` are what the endpoint actually calls
           // these; `name` and `count` would read better and are not there.
-          const label = Number.isFinite(entry.archives)
-            ? `${entry.category} (${entry.archives})`
-            : entry.category;
-          urls.append(
-            urlRow(label, new URL(entry.endpoints.styleUrl, location.href).href),
-          );
+          const card = el('div', 'archive');
+          const head = el('header');
+          head.append(el('span', 'name', entry.category));
+          if (Number.isFinite(entry.archives)) {
+            head.append(
+              el(
+                'span',
+                'tag',
+                `${entry.archives} build${entry.archives === 1 ? '' : 's'}`,
+              ),
+            );
+          }
+          card.append(head);
+
+          if (entry.newest?.name) {
+            const facts = [`newest: ${entry.newest.name}`];
+            const size = bytes(entry.newest.size);
+            if (size) facts.push(size);
+            card.append(el('p', 'facts', facts.join(' · ')));
+          }
+
+          const links = el('div', 'links');
+          const add = (href, text) => {
+            const a = el('a', null, text);
+            a.href = href;
+            links.append(a);
+          };
+          const ends = entry.endpoints;
+          if (ends.tileJson) add(ends.tileJson, 'TileJSON');
+          if (ends.torrent) add(ends.torrent, '.torrent');
+          if (ends.magnet) add(ends.magnet, 'magnet');
+          if (ends.feed) add(ends.feed, 'RSS');
+          card.append(links);
+
+          const urls = el('div', 'urls');
+          // The one worth copying: the TileJSON URL with the magnet in its
+          // fragment, which a plain client fetches over HTTP and a swarm-aware
+          // one joins directly.
+          if (ends.styleUrl) {
+            urls.append(
+              urlRow('style URL', new URL(ends.styleUrl, location.href).href),
+            );
+          } else if (ends.tileJson) {
+            urls.append(
+              urlRow('TileJSON', new URL(ends.tileJson, location.href).href),
+            );
+          }
+          if (urls.childElementCount > 0) card.append(urls);
+
+          host.append(card);
         }
-        host.append(urls);
+
         host.append(el('h2', null, 'Archives'));
       };
-
       const PMTILES_NS =
         'https://github.com/TechIdiots-LLC/pmtiles-swarm/ns/1.0';
 
@@ -381,11 +442,17 @@
 
         render(archives.filter((archive) => archive.infoHash));
 
-        // Best effort, and after the archives: this one is guarded on an
-        // authenticated node and the page is worth showing without it.
+        // /latest/ rather than /api/categories: the same list, without a
+        // credential. This is the part most visitors actually want -- an
+        // archive URL names one build, a category names whichever is current
+        // -- so it is worth more than a best-effort attempt at a guarded
+        // endpoint that answers 401 to exactly the audience this page is for.
         try {
-          const response = await fetch('/api/categories');
-          if (response.ok) renderCategories(await response.json());
+          const response = await fetch('/latest/');
+          if (response.ok) {
+            const body = await response.json();
+            renderCategories(body.categories ?? []);
+          }
         } catch {
           // Nothing to say. The archives above are the substance.
         }