pmtiles-swarm 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -7,6 +7,80 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 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.**
+  0.9.0 said the 0% was the dropped `seedOnly`. That was half of it — the half that made the
+  archive *slow*. The half that made it *invisible* was in the sidecar: creation defaults to a
+  hybrid v1+v2 torrent, and libtorrent answers `info_hash()` for a hybrid with the truncated v2
+  hash, while the catalog, the magnet and every v1 peer use v1. The engine held the archive under
+  a name the catalog could not look up, so a correctly seeding archive was reported as one the
+  engine had never heard of, and no tile could be served from it. The dependency floor moves to
+  0.4.2 rather than being left to whatever a fresh install happens to resolve.
+
+  Expect hybrid archives to re-check once on the first start after upgrading: their resume files
+  are now looked for under the corrected name, and the old ones are not found.
+- **The service documentation pointed its status check at a path that does not exist.** It named
+  `/opt/pmtiles-swarm/src`, while a node installed the way the rest of that document describes has
+  its executable in `/var/lib/pmtiles-swarm/node_modules/.bin`. Running the documented command
+  found no dependencies and failed on the first import — which is the same
+  wrong-command-in-documentation problem the status command exists to end.
+
 ## 0.9.0
 ### ✨ Features and improvements
 - **`pmtiles-swarm status`**, which asks a running node what it is doing and reads the answer out

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/running-as-a-service.md

@@ -441,10 +441,13 @@ Then check it is actually serving:
 
 ```sh
 curl -fsS localhost:8090/feed.xml >/dev/null && echo "public surface ok"
-node /opt/pmtiles-swarm/src/index.js status \
-  --config /etc/pmtiles-swarm/swarm.config.json
+sudo -u pmtiles-swarm -H /var/lib/pmtiles-swarm/node_modules/.bin/pmtiles-swarm \
+  status --config /etc/pmtiles-swarm/swarm.config.json
 ```
 
+Safe to run against a live node: it asks over HTTP and takes no lock, so it is
+not the second process the data directory would refuse.
+
 Ask through the status command rather than with `curl`. Reaching the API by hand
 means getting the bind address, the admin port and the credential right in one
 go, and each of them fails in a way that looks like a broken node: a node bound

package/docs/serving-tiles.md

@@ -160,6 +160,72 @@ 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.
+
 ## 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.0",
+  "version": "0.11.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",
@@ -39,7 +39,7 @@
     "maplibre-gl": "^6.2.0",
     "parse-torrent": "^11.0.24",
     "pmtiles": "^4.4.1",
-    "pmtiles-torrent": "^0.4.0",
+    "pmtiles-torrent": "^0.4.2",
     "webtorrent": "^3.0.21"
   },
   "engines": {

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,25 @@ const DEFAULTS = {
    * instead sidesteps the question entirely.
    */
   trustProxy: false,
+  /**
+   * 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';
@@ -236,6 +237,14 @@ 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 });
+
   const tiles = new TileStore({ catalog, engine, config });
   library.attachTiles(tiles);
   const warm = new WarmRunner(tiles);
@@ -291,6 +300,7 @@ PMTILES_SWARM_PUBLIC_URL
     warm,
     config,
     speed,
+    stats,
     reloaders,
     shutdown: () => runStoppers(stoppers),
   });

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/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');