pmtiles-swarm 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.14.0
+### ✨ Features and improvements
+- **The Categories page hands you the URL a style should actually use.** A new **For a style** row
+  gives the category's TileJSON URL with a magnet in its fragment, which is the string worth
+  copying — the plain TileJSON row is still there for anything that only speaks HTTP.
+
+  Where a publisher is announcing the category over the DHT, the fragment carries the **mutable**
+  magnet (`xs=urn:btpk:…&s=<category>`), which is the form a category needs: it names the category
+  rather than a build, so it does not go stale on the next one while the URL keeps following it.
+  Without a publisher it falls back to the newest build's own magnet, which pins that build but
+  still beats a blank map on the only occasion it is read at all.
+
+  Also on `GET /api/categories` as `endpoints.styleUrl`, and `null` for a category whose newest
+  archive is not PMTiles — the same rule the tile endpoints already follow.
+
+  The magnet was already available on an individual archive, but a category URL is what a style
+  points at, and that is the page where it was missing.
+
+### 🐞 Bug fixes
+- **CI and the release workflow install with `--ignore-scripts`.** The 0.14.0 release failed in
+  `npm ci` because `node-datachannel` — WebTorrent's WebRTC binary, four levels down the tree —
+  found no prebuilt binary for the runner and crashed trying to build from source. The same
+  lockfile had published minutes earlier, so it was the download rather than an incompatibility.
+
+  Nothing in CI needs that binary: the suite passes without it, and `npm publish` ships source
+  rather than `node_modules`, so install scripts have no bearing on what is published. A
+  third-party binary download should not be able to block a release. Whether WebRTC works on a
+  given machine is still checked where it matters, after installing on the host.
+
 ## 0.13.1
 ### 🐞 Bug fixes
 - **A node with a secondary engine no longer takes a quarter of an hour to start listening.**

package/package.json

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

@@ -14,6 +14,7 @@ import {
   isPublicSurface,
 } from './auth.js';
 import { normalizeCategories } from './catalog.js';
+import { mutableMagnet } from './mutable.js';
 import { guessKind } from './library.js';
 import { QBittorrentEngine } from './engines/qbittorrent.js';
 import { RESTART_REQUIRED, redactConfig, saveConfig } from './config.js';
@@ -60,6 +61,25 @@ function route(handler) {
  * @param {object} deps.config - Resolved configuration.
  * @returns {import('express').Express} - The configured app.
  */
+/**
+ * A TileJSON URL carrying a magnet in its fragment.
+ * @param {string} category - Which category.
+ * @param {object} newest - Its newest entry.
+ * @param {string} base - Public base URL.
+ * @returns {string} - The URL a style should use.
+ */
+function styleUrlFor(category, newest, base) {
+  const url = `${base}/latest/${category}/tiles.json`;
+  const magnet = newest?.mutable?.publicKey
+    ? mutableMagnet(newest.mutable.publicKey, {
+        salt: newest.mutable.salt ?? category,
+        name: newest.name,
+        webSeeds: newest.webSeeds,
+      })
+    : newest?.magnet;
+  return magnet ? `${url}#${magnet}` : url;
+}
+
 export function createApp({
   library,
   catalog,
@@ -1703,6 +1723,18 @@ export function createApp({
             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`,

package/src/web/index.html

@@ -2356,6 +2356,7 @@
             const newest = entry.newest;
             const rows = [
               ['TileJSON', entry.endpoints.tileJson],
+              ['For a style', entry.endpoints.styleUrl],
               ['Torrent', entry.endpoints.torrent],
               ['Magnet', entry.endpoints.magnet],
               ['Feed', entry.endpoints.feed],
@@ -2384,7 +2385,20 @@
                             <td style="width:8rem">${label}</td>
                             <td>${
                               url
-                                ? `<code>${escapeHtml(url)}</code>`
+                                ? `<code>${escapeHtml(
+                                    url.length > 96 ? `${url.slice(0, 96)}…` : url,
+                                  )}</code>${
+                                    label === 'For a style'
+                                      ? `<div class="sub">the magnet rides in the fragment, which is
+                                         never sent to the server — an ordinary client fetches the
+                                         TileJSON and ignores it, a swarm-aware one reads it before
+                                         making any call${
+                                           url.includes('xs=urn:btpk')
+                                             ? ' and follows the category rather than this build'
+                                             : ''
+                                         }</div>`
+                                      : ''
+                                  }`
                                 : '<span class="sub">not a PMTiles archive, so there is no tile endpoint</span>'
                             }</td>
                             <td style="width:11rem">${
@@ -2406,6 +2420,7 @@
           const [index, row] = button.dataset.copy.split('-').map(Number);
           const url = [
             categories[index].endpoints.tileJson,
+            categories[index].endpoints.styleUrl,
             categories[index].endpoints.torrent,
             categories[index].endpoints.magnet,
             categories[index].endpoints.feed,