pmtiles-swarm 0.9.1 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,100 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.12.0
+### ✨ Features and improvements
+- **A category can now be addressed without a server at all.** A node that builds can publish a
+  signed DHT record (BEP 46) naming whichever archive is currently newest in each category, so a
+  style can point at a magnet that never goes stale:
+
+  ```
+  magnet:?xs=urn:btpk:<public key>&s=openmaptiles&dn=…&ws=…
+  ```
+
+  No infohash in it, which is the whole point — an infohash is what goes stale on the next build,
+  and it is why the fragment convention added in 0.11.0 could not be used for `/latest/` URLs. The
+  salt is the category name, so **one keypair addresses every category** rather than needing one
+  each.
+
+  Turn it on with `mutable.publish` and a key from the new **`pmtiles-swarm publisher-key`**
+  command. Off by default.
+
+  **Only the node that builds needs the key.** Serving nodes receive the public half on the catalog
+  entry, through the same sync that already carries `magnet` and `webSeeds`, and assemble the
+  identical magnet from it — there is nothing secret in one. Ten nodes behind a balancer hand out
+  the same string and none of them can publish. Run exactly one publisher: two under one key would
+  fight over the sequence number.
+
+  It is a **signing key rather than a credential**. Whoever holds it can tell your subscribers that
+  any archive is the current build, signed, and clients will believe it.
+
+  Records expire from the DHT after roughly two hours, so the node republishes on a timer
+  (`republishSeconds`, default 1800). That timer is the feature, not an optimisation — without it
+  a record published once works all afternoon and quietly stops resolving by evening. A category
+  whose put fails does not stop the others.
+
+  **`bittorrent-dht` is now a direct dependency** rather than reached for through webtorrent's
+  client, so publishing works on a node running the libtorrent engine alone.
+- **The TileJSON's `torrent.mutable` block carries the magnet**, built from the public key, so no
+  consumer has to know how to assemble one. `mutableMagnet()` also accepts a hex key now — which
+  is all a serving node has — and carries `ws=` web seeds, so a client with no peers can still
+  range-read the archive over HTTP.
+
+## 0.11.0
+### ✨ Features and improvements
+- **The magnet can travel in the TileJSON URL's fragment**, and the console will build that string
+  for you: **Copy TileJSON URL + magnet**. A fragment is never sent in an HTTP request, so one
+  string serves every client — maplibre-gl-js, Leaflet and plain maplibre-native fetch the
+  TileJSON and ignore it, while a torrent-aware client reads the magnet **before making any network
+  call at all**.
+
+  That last part is the point. The `torrent` block inside the TileJSON only helps once the TileJSON
+  has been fetched, which leaves the swarm — the one part that depends on no server —
+  unreachable exactly when the server is down. With the magnet in the fragment a client can fall
+  back to the `ws=` web seed (two range requests, and the TileJSON derives from the archive's own
+  header and metadata) or to the swarm itself.
+
+  Documented in [docs/serving-tiles.md](docs/serving-tiles.md), including the caveat worth knowing:
+  on a `/latest/<category>/` URL the fragment pins the build that was current when it was copied,
+  while the URL keeps following the category, so the two can disagree after a rebuild. Survivable,
+  since the fragment is only consulted when the TileJSON cannot be fetched and an older build
+  renders where a blank map does not — and properly fixed by a mutable `xs=urn:btpk:` magnet,
+  which needs the BEP 46 publishing that [src/mutable.js](src/mutable.js) has machinery for and
+  nothing yet calls.
+
+## 0.10.0
+### ✨ Features and improvements
+- **`GET /api/stats`**, which answers what a node has actually served. Until now a tile request was
+  answered and forgotten, so the most ordinary operational questions had no answer at all: which
+  archive is carrying the load, which zooms are being pulled, whether a node behind a balancer is
+  getting its share, and whether the traffic hammering it arrived directly or through the proxy.
+
+  Per-archive counters — requests, bytes, a breakdown by zoom and by status, p50/p95 latency, and
+  a count per client address — plus a fixed ring of the most recent requests. Both live in memory
+  and are bounded, so the cost is the same after a billion tiles as after ten. Nothing is written
+  to disk: a restart is how you reset it, and an access log would bring retention and disk
+  questions this deliberately does not have. `DELETE /api/stats` clears it, deliberately a separate
+  verb so a dashboard polling the endpoint cannot erase the history it is drawing.
+
+  The report names the node that answered, which is the point behind a load balancer — ask each
+  one directly and the counters say how traffic is really distributed rather than how the balancer
+  believes it is. Admin-side rather than public, because it lists archives and client addresses.
+
+  Bytes are counted **as sent**, so a gzipped vector tile counts its compressed size. That is the
+  number that matters for bandwidth and it is not what the client ends up holding.
+
+  What a client address means depends on the proxy in front. Without `X-Forwarded-For` it is the
+  proxy's own address for everything arriving through it — still enough to separate direct
+  traffic from proxied, which is usually the question being asked, but not who sent it. For real
+  client addresses the proxy has to send the header and `trustProxy` has to name it.
+
+  Configured under `tileStats`: `recent` sets how many requests to keep, `0` keeps the counters and
+  drops the ring, and `false` turns the whole thing off, after which the endpoint answers 501.
+- **The archive detail shows what it has served**, in the console and on
+  `GET /api/torrents/<infohash>` as a `served` block. Worth reading next to `reading`: an archive
+  being read through the swarm while serving thousands of tiles is a different situation from one
+  doing neither.
+
 ## 0.9.1
 ### 🐞 Bug fixes
 - **Requires pmtiles-torrent 0.4.2, which is what actually makes a newly built archive visible.**

package/README.md

@@ -621,6 +621,61 @@ Exit status is 0 when the node answered and its engine is up, 1 when it did not
 works in a deployment script. `--json` gives the raw `/api/status` and `/api/torrents` replies for
 anything that wants to parse rather than read.
 
+## Seeing what a node is actually serving
+
+```sh
+curl -s -H "authorization: Bearer $KEY" http://172.16.1.49:8091/api/stats | jq
+```
+
+```json
+{
+  "node": "planetgen",
+  "since": "2026-08-12T14:02:11.004Z",
+  "requests": 18422,
+  "bytes": 743112904,
+  "archives": {
+    "4813a0e68e4b88def6d4ef3c4eabde84ffc0c068": {
+      "name": "planetiler-openmaptiles-260803.pmtiles",
+      "requests": 18422,
+      "bytes": 743112904,
+      "byZoom": { "0": 12, "7": 3311, "14": 9022 },
+      "byStatus": { "200": 18104, "204": 301, "404": 17 },
+      "clients": { "172.16.1.2": 17980, "172.16.1.41": 442 },
+      "p50ms": 3,
+      "p95ms": 41
+    }
+  },
+  "recent": [
+    { "at": "…", "ip": "172.16.1.41", "z": 14, "x": 4823, "y": 6155,
+      "status": 200, "bytes": 41221, "ms": 2 }
+  ]
+}
+```
+
+Counters per archive, plus a fixed ring of the most recent requests. Both live in
+memory and are bounded, so the cost is the same after a billion tiles as after
+ten, and a restart is how you reset it. Nothing is written to disk — an access
+log brings retention and disk questions this deliberately does not have.
+
+`node` names which machine answered, which is the point behind a load balancer:
+ask each node directly and the counters tell you how traffic is actually
+distributed, rather than what the balancer believes.
+
+**What the client address means depends on your proxy.** `clients` records what
+the process can see. Without `X-Forwarded-For` that is the proxy's own address
+for everything arriving through it — still enough to separate direct traffic
+from proxied, which is usually the question, but not who sent it. For real
+client addresses, have the proxy send the header and set `trustProxy` to name
+it; see [docs/haproxy.md](docs/haproxy.md).
+
+Bytes are counted **as sent**, so a gzipped vector tile counts its compressed
+size. That is the number that matters for bandwidth, and it is not what the
+client ends up holding.
+
+Configured under `tileStats`: `recent` sets how many requests to keep (`0` keeps
+the counters and drops the ring), and `"tileStats": false` turns it off, after
+which the endpoint answers 501.
+
 ## API
 
 | Method | Path | Purpose |
@@ -655,6 +710,7 @@ anything that wants to parse rather than read.
 | `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` `DELETE` | `/api/stats` | What this node has served — per-archive counters and the last N requests; `DELETE` clears them |
 | `GET` `PATCH` | `/api/config` | Read and change settings |
 | `POST` | `/api/login`, `/api/logout` | Console sign-in |
 | `GET` | `/api/session` | Who this request is, and whether a credential is needed at all |

package/docs/serving-tiles.md

@@ -160,6 +160,120 @@ Both peer-to-peer engines reuse the client already seeding the archive rather
 than starting a second one. One peer pool, one port, one DHT node — and for
 libtorrent, one sidecar process.
 
+## Carrying the magnet in the URL fragment
+
+The `torrent` block below solves the problem *after* the TileJSON has been
+fetched. It does not solve the one before it: a torrent-aware client that cannot
+reach this server has nothing to work with, so the swarm — the part that does
+not depend on any server — is unreachable precisely when the server is down.
+
+The fix is to put the magnet in the URL **fragment**:
+
+```json
+"sources": {
+  "openmaptiles": {
+    "type": "vector",
+    "url": "https://swarm.example.org/latest/openmaptiles/tiles.json#magnet:?xt=urn:btih:4813a0e6…&dn=…&tr=…&ws=…"
+  }
+}
+```
+
+A fragment is never sent in an HTTP request, so the same string works
+everywhere:
+
+| Client | What happens |
+| --- | --- |
+| maplibre-gl-js, Leaflet, anything | fetches the TileJSON, ignores the fragment |
+| maplibre-native without a plugin | the same |
+| torrent-aware | reads the magnet **before any network call**, and still has it if the fetch fails |
+
+The console's **Copy TileJSON URL + magnet** button produces exactly this.
+
+A magnet needs no encoding in a fragment — RFC 3986 allows `?`, `&`, `=` and `:`
+there — and leaving it readable matters for something people paste into a style
+file by hand.
+
+### What a client should do with it
+
+Three paths, each a strict fallback of the one above:
+
+1. **The TileJSON URL.** One request, the full document including
+   `vector_layers`. Fastest, and what an ordinary client does anyway.
+2. **The `ws=` web seed.** Two HTTP range requests — the header and root
+   directory near the start of the archive, the JSON metadata at the far end —
+   and the TileJSON can be derived from them. Works when this API is down but
+   the file is still on a web server, and it is the same order of cost as (1).
+3. **The swarm.** No HTTP at all. Slowest from cold, because BEP 9 has to
+   deliver the metainfo first, and the only one that survives the server
+   disappearing entirely.
+
+Everything those need is in the magnet: `xt` identifies the archive, `dn` names
+the file, `tr` finds peers, `ws` gives the HTTP fallback.
+
+### One caveat on `/latest/` URLs
+
+`/latest/<category>/tiles.json` follows the category, and a magnet naming an
+infohash does not — it pins the build that was current when the URL was copied.
+So the fragment goes stale on the next build while the URL does not.
+
+That is survivable, because the fragment is only consulted when the TileJSON
+cannot be fetched, and an older build renders where a blank map does not. But it
+means the two halves can disagree, and the fix is a **mutable** magnet
+(`xs=urn:btpk:…`, BEP 46) whose target is resolved over the DHT rather than
+baked into the string. See [src/mutable.js](../src/mutable.js) — note that
+nothing publishes those records yet.
+
+For an immutable `/archives/<infohash>/tiles.json` URL the question does not
+arise: both halves name the same fixed archive.
+
+### A fragment that survives a rebuild
+
+The caveat above — a pinned infohash going stale — is what BEP 46 fixes. A node
+that publishes signs a DHT record naming whichever infohash is current, and the
+magnet then names the **category** rather than a build:
+
+```
+magnet:?xs=urn:btpk:<public key>&s=openmaptiles&dn=…&ws=…
+```
+
+No infohash anywhere, so nothing to go stale. A client resolves the record over
+the DHT and joins whatever is current.
+
+Turn it on with a key on the node that builds:
+
+```sh
+pmtiles-swarm publisher-key > /etc/pmtiles-swarm/publisher.pem
+chmod 600 /etc/pmtiles-swarm/publisher.pem
+```
+
+```json
+{ "mutable": { "publish": true, "keyPath": "/etc/pmtiles-swarm/publisher.pem" } }
+```
+
+The magnet then appears in every TileJSON as `torrent.mutable.magnet`, and the
+console's copy button uses it for category URLs.
+
+**Only the node that builds needs the key.** Serving nodes receive the public
+half on the catalog entry, through the same subscription sync that carries
+`magnet` and `webSeeds`, and assemble the identical magnet from it — there is
+nothing secret in one. Ten nodes behind a balancer hand out the same string and
+none of them can publish.
+
+**Run exactly one publisher.** Two nodes publishing under one key would fight
+over the sequence number, each overwriting the other's claim about what is
+current.
+
+**It is a signing key, not a credential.** Whoever holds it can tell your
+subscribers that any archive is the current build, signed, and they will believe
+it. Treat it the way you would a code-signing key: lose it and every style
+pointing at that public key breaks permanently.
+
+**Records expire after roughly two hours**, so the node republishes on a timer
+(`republishSeconds`, default 1800). That timer is not an optimisation — without
+it a record published once works all afternoon and stops resolving by evening.
+If the publisher is offline longer than that, the DHT path goes quiet until it
+returns; the HTTP TileJSON URL is unaffected.
+
 ## The `torrent` block
 
 TileJSON documents from this server carry a non-standard `torrent` member:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.9.1",
+  "version": "0.12.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",
@@ -32,6 +32,7 @@
   "dependencies": {
     "@maplibre/maplibre-gl-inspect": "^1.8.2",
     "bencode": "^4.0.1",
+    "bittorrent-dht": "^11.0.12",
     "chokidar": "^5.0.0",
     "create-torrent": "^6.1.0",
     "express": "^5.2.1",

package/src/api.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
@@ -70,6 +71,7 @@ export function createApp({
   warm,
   config,
   speed,
+  stats,
   reloaders = {},
   shutdown,
 }) {
@@ -496,6 +498,39 @@ export function createApp({
     }),
   );
 
+  // What this node has served, which is a different question from whether it
+  // is healthy. Admin-side: it names archives and client addresses, and a
+  // public endpoint reporting who else is using a node is a privacy question
+  // nobody asked for.
+  app.get(
+    '/api/stats',
+    route(async (req, res) => {
+      if (!stats) {
+        return res.status(501).json({ error: 'tile statistics are disabled' });
+      }
+      const recent = req.query.recent === undefined ? undefined : Number(req.query.recent);
+      res.setHeader('cache-control', 'no-store');
+      res.json({
+        node: config.nodeName ?? os.hostname(),
+        ...stats.snapshot({ recent }),
+      });
+    }),
+  );
+
+  // Deliberately a separate verb: reading counters should never be able to
+  // clear them, or a dashboard polling the endpoint would erase the history
+  // it is drawing.
+  app.delete(
+    '/api/stats',
+    route(async (_req, res) => {
+      if (!stats) {
+        return res.status(501).json({ error: 'tile statistics are disabled' });
+      }
+      stats.reset();
+      res.status(204).end();
+    }),
+  );
+
   // Settings. Everything read per request takes effect immediately because the
   // running config object is the one being mutated; everything bound at startup
   // is written to the file and reported back as needing a restart, rather than
@@ -730,7 +765,12 @@ export function createApp({
       // Optional call: a missing method throws before any .catch could see it.
       const diskBytes =
         (await library.diskUsage?.(entry.infoHash).catch(() => null)) ?? null;
-      res.json({ ...entry, status, reading, diskBytes });
+      // Null until a tile has been asked for, and reset by a restart — the
+      // same lifetime as `reading`, and worth reading alongside it: an archive
+      // being read through the swarm while serving thousands of tiles is a
+      // different situation from one doing neither.
+      const served = stats?.forArchive(entry.infoHash) ?? null;
+      res.json({ ...entry, status, reading, diskBytes, served });
     }),
   );
 
@@ -2033,6 +2073,31 @@ export function createApp({
         if (!res.writableEnded) controller.abort();
       });
 
+      // Counted on the way out rather than at each return: this handler ends
+      // in six different places (200, 204, 404, 415, 400, a read error), and
+      // one hook catches all of them without any of them having to remember.
+      // Abandoned requests are not counted -- a panning map cancels constantly
+      // and those were never served.
+      if (stats) {
+        const startedAt = process.hrtime.bigint();
+        res.on('finish', () => {
+          stats.record({
+            infoHash,
+            name: entry.name,
+            z,
+            x,
+            y,
+            status: res.statusCode,
+            bytes: Number(res.getHeader('content-length')) || 0,
+            ms: Number(process.hrtime.bigint() - startedAt) / 1e6,
+            // Whatever this process can see. Behind a proxy that sends no
+            // X-Forwarded-For this is the proxy's address, which is itself
+            // the answer to "did this arrive directly or through HAProxy".
+            ip: req.ip,
+          });
+        });
+      }
+
       let tile;
       try {
         tile = await tiles.getTile(infoHash, z, x, y, {

package/src/config.js

@@ -397,6 +397,54 @@ const DEFAULTS = {
    * instead sidesteps the question entirely.
    */
   trustProxy: false,
+  /**
+   * Announcing the current build of each category over the DHT (BEP 46).
+   *
+   * A category is the only stable handle this system has — every archive is
+   * addressed by its infohash, so a style pointing at one goes stale on the
+   * next build. `/latest/<category>/` fixes that with a server; this fixes it
+   * without one, as a signed DHT record naming whichever infohash is current.
+   *
+   * **Only the node that builds needs this.** Serving nodes carry the public
+   * half on the catalog entry and hand it out in the TileJSON; publishing is
+   * the only thing the secret is used for. Two nodes publishing under one key
+   * would fight over the sequence number, so run exactly one publisher.
+   *
+   * The key is a signing key, not a credential: whoever holds it can tell your
+   * subscribers that any archive is the current build, signed. Treat it the way
+   * you would a code-signing key. Generate one with
+   * `pmtiles-swarm publisher-key`.
+   *
+   * Records expire from the DHT after roughly two hours, so this republishes on
+   * a timer. Nothing else keeps them alive.
+   */
+  mutable: {
+    /** Publish records. Off unless a key is configured and this is set. */
+    publish: false,
+    /** PEM file holding the ed25519 keypair. Never leaves the publisher. */
+    keyPath: undefined,
+    /** How often to republish, in seconds. */
+    republishSeconds: 1800,
+  },
+  /**
+   * What this node has served, at `GET /api/stats`.
+   *
+   * Per-archive counters and a fixed ring of recent requests, both in memory,
+   * so the cost does not grow with traffic. Nothing is written to disk: a
+   * restart is how you reset it, and an access log would bring retention and
+   * disk questions this deliberately does not have.
+   *
+   * `recent: 0` keeps the counters and drops the per-request ring. Setting
+   * `tileStats` to `false` turns the whole thing off.
+   *
+   * Note what the client address means behind a proxy: without
+   * `X-Forwarded-For` it is the proxy's own address, which still answers
+   * whether a request arrived directly or through it, but not who sent it.
+   */
+  tileStats: {
+    /** Recent requests kept for inspection. */
+    recent: 200,
+  },
   /**
    * Tile serving: a TileJSON endpoint and z/x/y tiles per archive.
    *

package/src/index.js

@@ -18,6 +18,7 @@ import { SeedingLimits } from './seeding.js';
 import { closeServer, installSignalHandlers, runStoppers } from './shutdown.js';
 import { ScheduledSourceManager } from './sources.js';
 import { SubscriptionManager } from './subscriptions.js';
+import { TileStats } from './tile-stats.js';
 import { TileStore } from './tiles.js';
 import { HeadWarmer } from './prewarm.js';
 import { WarmRunner } from './warm.js';
@@ -108,6 +109,7 @@ async function main() {
 Usage:
   pmtiles-swarm [--config FILE]          start the node
   pmtiles-swarm status [--config FILE]   ask a running node what it is doing
+  pmtiles-swarm publisher-key            print a new BEP 46 signing key
 
   --config, -c   path to a JSON config file
   --port,   -p   override the listen port
@@ -134,6 +136,20 @@ PMTILES_SWARM_PUBLIC_URL
     return;
   }
 
+  if (positionals[0] === 'publisher-key') {
+    const { generatePublisherKey, publisherKeyToPem } = await import('./mutable.js');
+    const key = generatePublisherKey();
+    // The PEM on stdout so it can be redirected to a file; everything else on
+    // stderr so that redirect stays clean.
+    process.stdout.write(publisherKeyToPem(key));
+    console.error('');
+    console.error(`public key: ${Buffer.from(key.publicKey).toString('hex')}`);
+    console.error('Save the PEM where only this node can read it, and point');
+    console.error('mutable.keyPath at it. It signs what your subscribers');
+    console.error('believe is the current build, so treat it as a signing key.');
+    return;
+  }
+
   if (positionals.length > 0) {
     console.error(`unknown command: ${positionals[0]}`);
     console.error('try: pmtiles-swarm status');
@@ -236,6 +252,50 @@ PMTILES_SWARM_PUBLIC_URL
     );
   }
 
+  // What this node has served. In memory and bounded, so it costs the same
+  // after a billion tiles as after ten; `tileStats.recent: 0` keeps the
+  // counters and drops the per-request ring, and `false` turns it off.
+  const stats =
+    config.tileStats === false
+      ? null
+      : new TileStats({ recent: config.tileStats?.recent });
+
+  // Announcing the current build of each category over the DHT. Only ever on
+  // the node that builds: the key signs what subscribers believe is current,
+  // and two publishers under one key would fight over the sequence number.
+  let publisher;
+  if (config.mutable?.publish && config.mutable?.keyPath) {
+    try {
+      const [{ publisherKeyFromPem }, { MutablePublisher }, DHT] = await Promise.all([
+        import('./mutable.js'),
+        import('./publisher.js'),
+        import('bittorrent-dht').then((m) => m.default),
+      ]);
+      const pem = await fs.readFile(config.mutable.keyPath, 'utf8');
+      const dht = new DHT();
+      publisher = new MutablePublisher({
+        catalog,
+        dht,
+        key: publisherKeyFromPem(pem),
+        intervalMs: (config.mutable.republishSeconds ?? 1800) * 1000,
+      });
+      stoppers.unshift({
+        label: 'mutable publisher',
+        stop: () => {
+          publisher.stop();
+          dht.destroy();
+        },
+        ms: 2000,
+      });
+      publisher.start();
+    } catch (error) {
+      // Never fatal: a node that cannot publish should still serve. Loudly
+      // reported, because the failure is otherwise invisible until a
+      // subscriber's style quietly stops resolving.
+      console.error(`[mutable] not publishing: ${error.message}`);
+    }
+  }
+
   const tiles = new TileStore({ catalog, engine, config });
   library.attachTiles(tiles);
   const warm = new WarmRunner(tiles);
@@ -291,6 +351,7 @@ PMTILES_SWARM_PUBLIC_URL
     warm,
     config,
     speed,
+    stats,
     reloaders,
     shutdown: () => runStoppers(stoppers),
   });

package/src/mutable.js

@@ -82,21 +82,35 @@ function rawPublicKey(publicKey) {
  *
  * Note this carries no infohash: `xs=urn:btpk:` names the public key, and the
  * client resolves it through the DHT to whatever infohash is current.
- * @param {Uint8Array} publicKey - Raw 32-byte public key.
+ * @param {Uint8Array | string} publicKey - Raw 32-byte public key, or its hex form.
+ *   A serving node has only the hex, off the catalog entry, and must be able to
+ *   build this string without ever seeing the raw key or the private half.
  * @param {object} [options] - Extra magnet parameters.
  * @param {string} [options.name] - Display name for the archive.
  * @param {string[]} [options.trackers] - Tracker announce URLs.
+ * @param {string[]} [options.webSeeds] - BEP 19 web seeds.
  * @param {string} [options.salt] - Salt, when one key publishes several archives.
  * @returns {string} - A BEP 46 magnet URI.
  */
 export function mutableMagnet(publicKey, options = {}) {
-  const hex = Buffer.from(publicKey).toString('hex');
+  // Buffer.from(string) would read hex as UTF-8 and produce a 64-byte key, so
+  // the two forms have to be told apart rather than coerced.
+  const hex =
+    typeof publicKey === 'string'
+      ? publicKey.toLowerCase()
+      : Buffer.from(publicKey).toString('hex');
   const parts = [`magnet:?xs=urn:btpk:${hex}`];
   if (options.name) parts.push(`dn=${encodeURIComponent(options.name)}`);
   if (options.salt) parts.push(`s=${encodeURIComponent(options.salt)}`);
   for (const tracker of options.trackers ?? []) {
     parts.push(`tr=${encodeURIComponent(tracker)}`);
   }
+  // Carried because it is what makes a magnet useful with no peers at all: a
+  // client can range-read the archive over HTTP and still be correct, which is
+  // the difference between a slow first paint and a blank map.
+  for (const seed of options.webSeeds ?? []) {
+    parts.push(`ws=${encodeURIComponent(seed)}`);
+  }
   return parts.join('&');
 }
 

package/src/publisher.js

@@ -0,0 +1,178 @@
+/**
+ * Announcing the current build of a category over the DHT (BEP 46).
+ *
+ * A category is the only stable handle this system has. Every archive is
+ * addressed by its infohash, which is what makes a tile immutable and leaves a
+ * style with nothing to point at that survives a rebuild. `/latest/<category>/`
+ * solves that with a server; this solves it without one — a signed DHT record,
+ * addressed by public key, naming whichever infohash is current.
+ *
+ * Only the node that builds needs the private key. Serving nodes carry the
+ * public half on the catalog entry and hand it out in the TileJSON, and
+ * publishing is the only operation the secret is used for. Two nodes
+ * publishing under one key would fight over `seq`, so this is deliberately a
+ * single-publisher design.
+ *
+ * The salt is the category name, so one keypair addresses every category
+ * rather than needing one each.
+ *
+ * The part that rots quietly: DHT nodes drop mutable items after roughly two
+ * hours. A record published once works all afternoon and is gone by evening,
+ * so republishing on a timer is not an optimisation here — it is the feature.
+ */
+
+import { mutableMagnet, publishInfoHash } from './mutable.js';
+
+/** Republish well inside the ~2h a DHT keeps an item. */
+const DEFAULT_INTERVAL_MS = 30 * 60 * 1000;
+
+/** Grace period before the first publish, for the DHT to find peers. */
+const DEFAULT_READY_MS = 15_000;
+
+export class MutablePublisher {
+  #catalog;
+  #dht;
+  #key;
+  #intervalMs;
+  #timer = null;
+  #stopped = false;
+  #log;
+  /** Last published infohash per category, so an unchanged build stays quiet. */
+  #published = new Map();
+
+  /**
+   * @param {object} options - Wiring.
+   * @param {object} options.catalog - Catalog to read categories from.
+   * @param {object} options.dht - A bittorrent-dht instance.
+   * @param {object} options.key - Keypair from `publisherKeyFromPem`.
+   * @param {number} [options.intervalMs] - Republish interval.
+   * @param {Function} [options.log] - Where to report.
+   */
+  constructor({ catalog, dht, key, intervalMs, log = console.log }) {
+    this.#catalog = catalog;
+    this.#dht = dht;
+    this.#key = key;
+    this.#intervalMs = intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.#log = log;
+  }
+
+  /** @returns {string} - The public key, hex, which is safe to publish. */
+  get publicKeyHex() {
+    return Buffer.from(this.#key.publicKey).toString('hex');
+  }
+
+  /**
+   * The newest archive in each category — what a record points at.
+   * @returns {Map<string, object>} - Category to catalog entry.
+   */
+  #current() {
+    const newest = new Map();
+    for (const category of this.#catalog.categories()) {
+      // byCategory() is newest first, the same rule /latest/<category>/ uses,
+      // so the record and the endpoint cannot disagree about what is current.
+      const [entry] = this.#catalog.byCategory(category);
+      if (entry) newest.set(category, entry);
+    }
+    return newest;
+  }
+
+  /**
+   * Publishes every category once.
+   * @param {object} [options] - Behaviour.
+   * @param {boolean} [options.force] - Log even when nothing changed.
+   * @returns {Promise<object[]>} - What was published.
+   */
+  async publishAll(options = {}) {
+    const done = [];
+    for (const [category, entry] of this.#current()) {
+      if (this.#stopped) break;
+      // Republished even when unchanged: the record expires whether or not the
+      // build has moved. `force` only decides whether it is worth saying.
+      const changed = this.#published.get(category) !== entry.infoHash;
+      try {
+        const result = await publishInfoHash(this.#dht, this.#key, entry.infoHash, {
+          salt: category,
+        });
+        this.#published.set(category, entry.infoHash);
+        done.push({ category, infoHash: entry.infoHash, ...result });
+
+        // Stamped on the entry so the TileJSON's torrent block carries the
+        // identity without any endpoint needing to know a publisher exists.
+        await this.#catalog.put({
+          infoHash: entry.infoHash,
+          mutable: { publicKey: this.publicKeyHex, salt: category, seq: result.seq },
+        });
+
+        if (changed || options.force) {
+          this.#log(
+            `[mutable] ${category} -> ${entry.infoHash.slice(0, 12)} ` +
+              `(seq ${result.seq}, ${result.nodes} nodes)`,
+          );
+        }
+      } catch (error) {
+        // One category failing must not stop the rest.
+        this.#log(`[mutable] ${category} failed: ${error.message}`);
+      }
+    }
+    return done;
+  }
+
+  /**
+   * The magnet a style should point at for a category.
+   *
+   * Public key only — there is nothing secret in it, which is why every
+   * serving node can hand it out and none of them can publish.
+   * @param {string} category - Which category.
+   * @param {object} [entry] - Newest entry, for the name and web seeds.
+   * @returns {string} - A BEP 46 magnet URI.
+   */
+  magnetFor(category, entry) {
+    return mutableMagnet(this.#key.publicKey, {
+      salt: category,
+      name: entry?.name,
+      webSeeds: entry?.webSeeds,
+    });
+  }
+
+  /**
+   * Starts publishing, and keeps republishing before the records expire.
+   * @param {object} [options] - Timing.
+   * @param {number} [options.readyMs] - Grace before the first publish.
+   * @returns {void}
+   */
+  start(options = {}) {
+    // A put into a DHT that has not found peers yet reaches nobody, and
+    // bootstrapping is the first thing a fresh node does. Waiting costs one
+    // interval of staleness at worst and makes the first publish mean
+    // something.
+    const first = setTimeout(() => {
+      if (this.#stopped) return;
+      this.publishAll({ force: true }).catch((error) =>
+        this.#log(`[mutable] first publish failed: ${error.message}`),
+      );
+    }, options.readyMs ?? DEFAULT_READY_MS);
+    first.unref?.();
+
+    this.#timer = setInterval(() => {
+      this.publishAll().catch((error) =>
+        this.#log(`[mutable] republish failed: ${error.message}`),
+      );
+    }, this.#intervalMs);
+    this.#timer.unref?.();
+
+    this.#log(
+      `[mutable] publishing ${this.#catalog.categories().length} categories as ` +
+        `${this.publicKeyHex.slice(0, 16)}… every ${Math.round(this.#intervalMs / 60000)}m`,
+    );
+  }
+
+  /**
+   * Stops republishing.
+   * @returns {void}
+   */
+  stop() {
+    this.#stopped = true;
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = null;
+  }
+}

package/src/tile-stats.js

@@ -0,0 +1,249 @@
+/**
+ * What this node has actually served.
+ *
+ * A tile request is answered and forgotten, which leaves the most ordinary
+ * operational questions unanswerable: which archive is carrying the load, which
+ * zooms are being asked for, whether a node behind a balancer is getting its
+ * share, and whether the thing hammering it arrived directly or through the
+ * proxy. Everything here is in memory and bounded — counters that never grow
+ * past the number of archives, and a fixed ring of recent requests — so it
+ * costs the same whether the node has served a hundred tiles or a billion.
+ *
+ * Deliberately not persisted. Restarting is how you reset it, and a node that
+ * writes an access log has retention and disk questions this does not.
+ */
+
+/** How many recent requests to keep, when the config says nothing. */
+const DEFAULT_RECENT = 200;
+
+/** How many durations to keep per archive for percentiles. */
+const SAMPLE_SIZE = 512;
+
+/**
+ * A fixed-size sample of durations, for percentiles without unbounded memory.
+ *
+ * Keeps the most recent SAMPLE_SIZE values rather than a true reservoir: what
+ * an operator wants is "how is it behaving now", and an even sample over all
+ * time hides a node that became slow ten minutes ago.
+ */
+class Durations {
+  #values = [];
+  #next = 0;
+
+  /**
+   * Records one duration.
+   * @param {number} ms - How long the request took.
+   * @returns {void}
+   */
+  add(ms) {
+    if (!Number.isFinite(ms)) return;
+    if (this.#values.length < SAMPLE_SIZE) {
+      this.#values.push(ms);
+      return;
+    }
+    this.#values[this.#next] = ms;
+    this.#next = (this.#next + 1) % SAMPLE_SIZE;
+  }
+
+  /**
+   * The value below which the given fraction of samples fall.
+   * @param {number} fraction - Between 0 and 1.
+   * @returns {number | null} - Milliseconds, or null with no samples.
+   */
+  percentile(fraction) {
+    if (this.#values.length === 0) return null;
+    const sorted = [...this.#values].sort((a, b) => a - b);
+    const index = Math.min(
+      sorted.length - 1,
+      Math.max(0, Math.ceil(fraction * sorted.length) - 1),
+    );
+    return sorted[index];
+  }
+}
+
+/**
+ * Per-archive counters and a ring of recent requests.
+ */
+export class TileStats {
+  #archives = new Map();
+  #recent = [];
+  #recentNext = 0;
+  #limit;
+  #since = new Date().toISOString();
+  #total = 0;
+  #bytes = 0;
+
+  /**
+   * @param {object} [options] - Configuration.
+   * @param {number} [options.recent] - How many recent requests to keep.
+   */
+  constructor(options = {}) {
+    const asked = Number(options.recent);
+    // Zero is a meaningful answer — counters without the ring — so it is not
+    // treated as "unset". Negative or unparseable falls back to the default.
+    this.#limit = Number.isFinite(asked) && asked >= 0 ? Math.floor(asked) : DEFAULT_RECENT;
+  }
+
+  /**
+   * Records one served tile request.
+   * @param {object} entry - What was served.
+   * @param {string} entry.infoHash - Which archive.
+   * @param {string} [entry.name] - Its filename, for readability.
+   * @param {number} entry.z - Zoom.
+   * @param {number} [entry.x] - Column.
+   * @param {number} [entry.y] - Row.
+   * @param {number} entry.status - HTTP status answered.
+   * @param {number} [entry.bytes] - Body size.
+   * @param {number} [entry.ms] - How long it took.
+   * @param {string} [entry.ip] - Who asked, as seen by this process.
+   * @param {string} [entry.at] - ISO timestamp, for tests.
+   * @returns {void}
+   */
+  record(entry) {
+    const { infoHash, z, status } = entry;
+    if (!infoHash) return;
+
+    let archive = this.#archives.get(infoHash);
+    if (!archive) {
+      archive = {
+        name: entry.name,
+        requests: 0,
+        bytes: 0,
+        byZoom: new Map(),
+        byStatus: new Map(),
+        clients: new Map(),
+        durations: new Durations(),
+        firstSeen: entry.at ?? new Date().toISOString(),
+        lastSeen: null,
+      };
+      this.#archives.set(infoHash, archive);
+    }
+    // A rename or a later import can fill this in after the first request.
+    if (!archive.name && entry.name) archive.name = entry.name;
+
+    const bytes = Number.isFinite(entry.bytes) ? entry.bytes : 0;
+    archive.requests += 1;
+    archive.bytes += bytes;
+    archive.lastSeen = entry.at ?? new Date().toISOString();
+    archive.durations.add(entry.ms);
+    this.#total += 1;
+    this.#bytes += bytes;
+
+    if (Number.isInteger(z)) {
+      archive.byZoom.set(z, (archive.byZoom.get(z) ?? 0) + 1);
+    }
+    if (Number.isFinite(status)) {
+      archive.byStatus.set(status, (archive.byStatus.get(status) ?? 0) + 1);
+    }
+    if (entry.ip) {
+      // Counted rather than listed: a busy node sees a handful of distinct
+      // sources — the proxy, a few LAN clients — and the count is the answer
+      // to "is this arriving directly or through HAProxy".
+      const seen = archive.clients.get(entry.ip) ?? { requests: 0, bytes: 0 };
+      seen.requests += 1;
+      seen.bytes += bytes;
+      archive.clients.set(entry.ip, seen);
+    }
+
+    if (this.#limit === 0) return;
+    const row = {
+      at: archive.lastSeen,
+      ip: entry.ip ?? null,
+      infoHash,
+      name: archive.name ?? null,
+      z: Number.isInteger(z) ? z : null,
+      x: Number.isInteger(entry.x) ? entry.x : null,
+      y: Number.isInteger(entry.y) ? entry.y : null,
+      status: status ?? null,
+      bytes,
+      ms: Number.isFinite(entry.ms) ? entry.ms : null,
+    };
+    if (this.#recent.length < this.#limit) {
+      this.#recent.push(row);
+    } else {
+      this.#recent[this.#recentNext] = row;
+      this.#recentNext = (this.#recentNext + 1) % this.#limit;
+    }
+  }
+
+  /**
+   * Everything recorded, as plain JSON.
+   * @param {object} [options] - Shaping.
+   * @param {number} [options.recent] - How many recent rows to return.
+   * @returns {object} - The report.
+   */
+  snapshot(options = {}) {
+    const archives = {};
+    for (const infoHash of this.#archives.keys()) {
+      archives[infoHash] = this.forArchive(infoHash);
+    }
+
+    const asked = Number(options.recent);
+    const wanted = Number.isFinite(asked) && asked >= 0 ? Math.floor(asked) : this.#limit;
+
+    return {
+      since: this.#since,
+      requests: this.#total,
+      bytes: this.#bytes,
+      archives,
+      recent: this.recent(wanted),
+    };
+  }
+
+  /**
+   * What one archive has served, or null if it has served nothing.
+   *
+   * Separate from snapshot() so the per-archive detail endpoint can answer
+   * "what is this one doing" without building a report about every other.
+   * @param {string} infoHash - Which archive.
+   * @returns {object | null} - Its counters.
+   */
+  forArchive(infoHash) {
+    const a = this.#archives.get(infoHash);
+    if (!a) return null;
+    return {
+      name: a.name ?? null,
+      requests: a.requests,
+      bytes: a.bytes,
+      byZoom: Object.fromEntries([...a.byZoom].sort((x, y) => x[0] - y[0])),
+      byStatus: Object.fromEntries([...a.byStatus].sort((x, y) => x[0] - y[0])),
+      clients: Object.fromEntries(
+        [...a.clients]
+          .sort((x, y) => y[1].requests - x[1].requests)
+          .map(([ip, seen]) => [ip, seen.requests]),
+      ),
+      p50ms: a.durations.percentile(0.5),
+      p95ms: a.durations.percentile(0.95),
+      firstSeen: a.firstSeen,
+      lastSeen: a.lastSeen,
+    };
+  }
+
+  /**
+   * The most recent requests, newest first.
+   * @param {number} [count] - How many to return.
+   * @returns {object[]} - Recent rows.
+   */
+  recent(count = this.#limit) {
+    if (this.#recent.length === 0 || count <= 0) return [];
+    // The ring is oldest-first from the write cursor once it has wrapped.
+    const ordered =
+      this.#recent.length < this.#limit
+        ? [...this.#recent]
+        : [...this.#recent.slice(this.#recentNext), ...this.#recent.slice(0, this.#recentNext)];
+    return ordered.reverse().slice(0, count);
+  }
+
+  /**
+   * Forgets everything, as a restart would.
+   * @returns {void}
+   */
+  reset() {
+    this.#archives.clear();
+    this.#recent = [];
+    this.#recentNext = 0;
+    this.#total = 0;
+    this.#bytes = 0;
+    this.#since = new Date().toISOString();
+  }
+}

package/src/tilejson.js

@@ -1,3 +1,4 @@
+import { mutableMagnet } from './mutable.js';
 import { TileStore } from './tiles.js';
 
 /**
@@ -95,6 +96,13 @@ function buildTorrentBlock(entry, root) {
       publicKey: entry.mutable.publicKey,
       salt: entry.mutable.salt,
       seq: entry.mutable.seq,
+      // Built here so a consumer does not have to know how to assemble one,
+      // and buildable by any node, because it contains only the public half.
+      magnet: mutableMagnet(entry.mutable.publicKey, {
+        salt: entry.mutable.salt,
+        name: entry.name,
+        webSeeds: entry.webSeeds,
+      }),
     };
   }
   return block;

package/src/web/index.html

@@ -1349,6 +1349,15 @@
             <div><span>origin</span><b>${escapeHtml(originOf(entry).label)}</b>
               <span class="sub">${escapeHtml(originOf(entry).detail)}</span></div>
             <div><span>reading via</span><b>${escapeHtml(entry.reading?.mode ?? 'not open')}</b></div>
+            <div><span>tiles served</span><b>${
+              entry.served ? entry.served.requests.toLocaleString() : '—'
+            }</b><span class="sub">${
+              entry.served
+                ? `${bytes(entry.served.bytes)} sent · ${
+                    entry.served.p50ms === null ? '—' : `${Math.round(entry.served.p50ms)} ms`
+                  } median`
+                : 'since this node started'
+            }</span></div>
             <div><span>format</span><b>${escapeHtml(summary.format ?? '—')}</b></div>
             <div><span>zoom</span><b>${summary.minZoom ?? '—'}–${summary.maxZoom ?? '—'}</b></div>
             <div><span>web seeds</span><b>${(entry.webSeeds ?? []).length}</b></div>
@@ -1371,6 +1380,7 @@
             <button id="copy-magnet">Copy magnet</button>
             <button id="copy-hash">Copy infohash</button>
             ${servable ? `<button id="copy-tilejson">Copy TileJSON URL</button>
+            <button id="copy-tilejson-swarm" title="The same URL with the magnet in the fragment. A fragment is never sent to the server, so ordinary clients fetch the TileJSON exactly as before; a torrent-aware client reads the magnet from it and can still join the swarm when this server is unreachable.">Copy TileJSON URL + magnet</button>
             <a href="${tileJson}" target="_blank" rel="noreferrer"><button type="button">Open TileJSON</button></a>
             <a href="${base}/archives/${entry.infoHash}/preview" target="_blank" rel="noreferrer"><button type="button">${
               summary.format === 'pbf' ? 'Inspect' : 'Preview'
@@ -1642,6 +1652,20 @@
         $('copy-magnet').onclick = () => copy(entry.magnet ?? '', 'Magnet link');
         if (servable) {
           $('copy-tilejson').onclick = () => copy(tileJson, 'TileJSON URL');
+          // The magnet rides in the fragment, which is client-side only and
+          // never sent in the request. So the same string serves both: an
+          // ordinary client fetches the TileJSON and ignores the fragment, and
+          // a torrent-aware one reads the magnet before making any call at all
+          // — which is what lets it start when this server is down.
+          //
+          // A magnet is legal in a fragment unencoded (RFC 3986 allows ?, &, =
+          // and : there), and leaving it readable matters for something people
+          // paste into a style file by hand.
+          $('copy-tilejson-swarm').onclick = () =>
+            copy(
+              entry.magnet ? `${tileJson}#${entry.magnet}` : tileJson,
+              entry.magnet ? 'TileJSON URL with magnet' : 'TileJSON URL (no magnet on this archive)',
+            );
         }
         $('copy-hash').onclick = () => copy(entry.infoHash, 'Infohash');