pmtiles-swarm 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# pmtiles-swarm changelog
+
+## master
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.2.0
+### ✨ Features and improvements
+- **Serve tiles.** Every archive now has a TileJSON endpoint and a `{z}/{x}/{y}` tile endpoint
+  under `/archives/{infohash}/`. A node holding a complete copy reads its local file; a node in
+  cache mode reads through the swarm via `pmtiles-torrent`, fetching only the pieces a requested
+  tile lives in and seeding them back.
+- The TileJSON carries a non-standard `torrent` block — infohash, magnet, `.torrent` URL, web
+  seeds and any BEP 46 publisher key. Ordinary clients ignore it and fetch over HTTP;
+  torrent-aware clients use it to join the swarm directly. One URL serves both.
+- Tiles are served `immutable` with a year-long max-age. An infohash pins content, so a tile
+  under one can never change, and an updated archive gets new URLs rather than needing a purge.
+- **Warm a region before serving it.** `POST /api/torrents/{infohash}/warm` pre-fetches the
+  tiles covering a bounding box, so a cache-mode node is useful the moment it enters a
+  load-balanced pool rather than paying for the first request to every area. Progress and
+  cancellation via `GET` and `DELETE` on the same path. The zoom range is clamped to what the
+  archive actually holds.
+- New `trustProxy` config option. With it set, absolute URLs in TileJSON and the RSS feed are
+  derived per request from `X-Forwarded-Proto` and `X-Forwarded-Host`, so one node can answer
+  correctly on both `https://public` and `http://internal`.
+- Depend on `pmtiles-torrent` from npm, and drop the local copy of the libtorrent sidecar in
+  favour of the one it ships. The two copies had drifted: the read side had grown `info` and
+  `set_priority` ops this project never got, which are exactly what on-demand tile reads need.
+- Upgrade WebTorrent to 3.x, dropping the `uint8-util` override that the 2.x line needed to add
+  magnets at all. **Node 20 is no longer supported** — WebTorrent 3 requires Node 22+, and Node
+  20 reached end of life in April 2026.
+
+### 🐞 Bug fixes
+- Absolute URLs used the raw `Host` header, which behind a reverse proxy is the internal address
+  the proxy dialled. They now follow `X-Forwarded-Host` when a proxy is trusted, so published
+  tile and feed URLs are reachable.
+- Stop tracking a compiled `.pyc` that predated the `__pycache__` ignore rule.
+
+## 0.1.0
+### ✨ Features and improvements
+- Initial release: BitTorrent distribution for PMTiles map archives.
+- Pluggable seeding engines: libtorrent (via sidecar), qBittorrent (WebUI API), and embedded WebTorrent.
+- Four ways to add an archive: local file, remote URL, existing torrent or magnet, and adoption of what the engine already seeds.
+- Web seeds (BEP 19) registered automatically, so a new archive is usable before it has any peers.
+- Mirror and cache modes; joining defaults to cache so a large archive cannot silently claim the disk.
+- Scheduled sources for upstreams publishing a new dated URL per build.
+- Origin change detection, with optional guarded auto-rebuild.
+- RSS publish and subscribe, with map metadata (format, zoom range, bounds) in each item.
+- Hybrid v1+v2 torrent creation through libtorrent.
+- BEP 46 mutable-torrent helpers.

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Andrew Calcutt and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE.md

@@ -0,0 +1,47 @@
+# Third-party notices
+
+`pmtiles-swarm` is licensed BSD-3-Clause (see [LICENSE](LICENSE)). This file records the
+third-party work it builds on.
+
+## PMTiles — BSD-3-Clause (reference implementation), CC0-1.0 (specification)
+
+> Copyright 2021 and later, Protomaps LLC and contributors
+> https://github.com/protomaps/PMTiles
+
+The `pmtiles` npm package is used at runtime to read archive headers and metadata. No
+implementation code is copied.
+
+## WebTorrent — MIT
+
+> Copyright (c) Feross Aboukhadijeh and WebTorrent, LLC
+> https://github.com/webtorrent/webtorrent
+
+`src/engines/webtorrent.js` is an adapter written against WebTorrent's public API.
+`src/mutable.js` builds on `bittorrent-dht`'s BEP 44 put/get. `create-torrent` and `parse-torrent`,
+from the same ecosystem and also MIT, are used for torrent creation and parsing. No implementation
+code is copied.
+
+Note the `uint8-util` override pinned in `package.json`: version 2.3.0 rewrote `arr2hex` in a way
+that throws when handed the hex-string infohash that webtorrent's `Torrent._onTorrentId` passes it,
+breaking every magnet add. webtorrent declares `^2.2.5`, so the pin holds it at a working version.
+Remove it once webtorrent fixes the call site.
+
+## qBittorrent — GPL-2.0-or-later
+
+> https://github.com/qbittorrent/qBittorrent
+
+**No qBittorrent code is used in this project.** `src/engines/qbittorrent.js` is a client for its
+documented WebUI HTTP API, written from the public API documentation. qBittorrent is GPL-2.0+,
+which is not compatible with redistribution under this project's BSD-3-Clause license, so code
+must not be copied from it. Speaking to a program over its network API does not create a derived
+work; copying its source would.
+
+The same caution applies to libtorrent-rasterbar if a libtorrent-backed engine is added later:
+libtorrent is BSD-3-Clause and therefore fine to link and derive from, but it must be pulled in
+directly rather than by way of any GPL client.
+
+## BitTorrent Enhancement Proposals
+
+The BEPs implemented here — BEP 19 (web seeds), BEP 44 (DHT storage) and BEP 46 (updating torrents
+via DHT mutable items) — are open specifications published by the BitTorrent community at
+https://www.bittorrent.org/beps/bep_0000.html.

package/README.md

@@ -0,0 +1,172 @@
+# pmtiles-swarm
+
+BitTorrent distribution built for PMTiles map archives.
+
+A torrent client and server that knows what a map is: it creates torrents from PMTiles archives,
+watches folders for new builds, publishes an RSS feed carrying each archive's coverage and zoom
+range, and follows other nodes' feeds to mirror or cache what they publish.
+
+It does not reimplement BitTorrent. Seeding is delegated to an engine — your existing qBittorrent,
+or an embedded WebTorrent client — so libtorrent keeps doing what it is good at.
+
+```sh
+npm install
+node src/index.js --config swarm.config.json
+# then open http://localhost:8090
+```
+
+## Documentation
+
+- **[docs/engines.md](docs/engines.md)** — libtorrent, qBittorrent and WebTorrent: what each
+  can do, what to install, and how cache mode differs between them.
+- **[docs/publishing.md](docs/publishing.md)** — creating torrents, web seeds, piece size,
+  hybrid v1+v2, watch folders, and the keep-or-discard choice when adding from a URL.
+- **[docs/subscribing.md](docs/subscribing.md)** — a worked two-node setup, mirror vs cache,
+  feed contents, and updatable torrents.
+- **[docs/serving-tiles.md](docs/serving-tiles.md)** — the TileJSON and z/x/y endpoints, the
+  `torrent` block that torrent-aware clients use, caching, and running behind a proxy.
+- **[docs/architecture-diagram.md](docs/architecture-diagram.md)** — how a publishing node, a
+  serving tier, the swarm and both kinds of client fit together.
+
+## What it does
+
+**Adds archives four ways.** A local `.pmtiles` file (hashed into a new torrent, data left where
+it is); a remote URL (see below); an existing `.torrent` or magnet, which it simply joins; or
+adoption of everything your torrent client already seeds — the migration path for an existing
+library, which re-hashes nothing.
+
+**Watches folders.** A new `.pmtiles` appearing in a watched folder is imported automatically.
+Imports wait for the file to stop changing first, because hashing a half-written archive produces
+a torrent for bytes that no longer exist.
+
+**Publishes RSS.** `/feed.xml`, and `/feed/<category>.xml` per category. Plain RSS 2.0 with
+torrent enclosures, so **qBittorrent's built-in RSS auto-downloader can subscribe today** with no
+new software. Items also carry a namespaced description of the map — format, zoom range, bounds,
+tile count — so a subscriber can decide whether it wants a 72 GiB download before starting one.
+
+**Follows feeds.** Subscribed feeds are polled and new archives added in one of two modes.
+
+**Serves tiles.** Every archive is also a TileJSON endpoint and a `{z}/{x}/{y}` tile endpoint, so
+a map can point straight at it. A node holding a complete copy reads its local file; a node in
+cache mode reads through the swarm, pulling only the pieces a requested tile lives in. The
+TileJSON carries a `torrent` block that ordinary clients ignore and torrent-aware ones use to
+join the swarm directly — one URL serves both. See
+[docs/serving-tiles.md](docs/serving-tiles.md).
+
+## Mirror and cache
+
+The distinction is the point of the project.
+
+| Mode | Disk cost | What it is for |
+| --- | --- | --- |
+| `mirror` | the whole archive | Becoming a full seeder and adding redundancy to the swarm |
+| `cache` | only what is read | Serving tiles from a 700 GiB archive on a small disk |
+
+Cache mode joins the swarm without downloading anything up front. A tile server reads byte ranges
+on demand through [`pmtiles-torrent`](https://github.com/TechIdiots-LLC/pmtiles-torrent), and the node still
+seeds whatever pieces it has picked up along the way. Disk use tracks what people actually look
+at rather than what exists.
+
+Joining a torrent **defaults to cache**, because committing a disk to a copy of something that may
+be hundreds of gigabytes should be a decision, not a side effect.
+
+Cache mode needs piece-level control. WebTorrent has it; qBittorrent's WebUI exposes only per-file
+priorities, which for a single-file archive is all or nothing — so under the qBittorrent engine,
+cache mode adds the torrent stopped and leaves on-demand reads to a client that can do them.
+
+## Adding from a URL
+
+Piece hashes are computed over content, so there is no way to create a torrent from a remote
+archive without reading every byte of it. What you choose is whether those bytes are kept:
+
+- **retain** (default) — written to disk as they arrive, so the node is a real seeder the moment
+  the torrent is published.
+- **discard** (`"retain": false`) — streamed past the hasher and dropped. No disk cost, but the
+  node cannot seed what it just published; peers depend on the web seed until someone mirrors it.
+
+Either way the origin URL is registered as a **web seed** (BEP 19), which is what makes a
+brand-new archive usable before it has any peers at all. If your archives are already on a web
+server or S3, always pass the URL — it turns cold start from a dead end into an HTTP fallback that
+gets cheaper as peers appear.
+
+## Updatable torrents
+
+A rebuilt archive is a different torrent: the infohash is a hash of the content. Two ways to carry
+subscribers forward, and they fail differently, so publishing both is cheap insurance.
+
+- **RSS** — easy to consume, understood by existing clients, needs a server that stays up.
+- **BEP 46** — an ed25519-signed DHT record naming the current infohash, addressed by public key
+  rather than infohash (`magnet:?xs=urn:btpk:…`). No server needed, but the record expires and must
+  be republished. See [src/mutable.js](src/mutable.js).
+
+## Configuration
+
+```json
+{
+  "port": 8090,
+  "dataDir": "./data",
+  "engine": "qbittorrent",
+  "qbittorrent": { "url": "http://127.0.0.1:8080", "username": "admin", "password": "…" },
+  "webtorrent": { "savePath": "./data/torrents-data" },
+  "pieceLength": 4194304,
+  "maxConnections": 100,
+  "feedMaxItems": 50,
+  "publicUrl": "https://maps.example.org",
+  "watch": [
+    { "path": "/mnt/maps/generated", "category": "basemaps", "webSeedBase": "https://maps.example.org/files" }
+  ],
+  "subscriptions": [
+    { "url": "https://other.example.org/feed.xml", "mode": "cache", "filter": "terrain" }
+  ]
+}
+```
+
+Environment overrides: `PMTILES_SWARM_PORT`, `PMTILES_SWARM_DATA_DIR`, `PMTILES_SWARM_ENGINE`,
+`PMTILES_SWARM_QBT_URL`, `PMTILES_SWARM_QBT_USERNAME`, `PMTILES_SWARM_QBT_PASSWORD`,
+`PMTILES_SWARM_PUBLIC_URL`.
+
+### Piece length
+
+Creation tools size pieces for whole-file downloads — 16 MiB or more for a large archive. That is
+a poor fit for a tile server, where a cold tile costs a whole piece regardless of how few bytes it
+needs. The default here is 4 MiB, trading a larger hash list for a quarter of the read
+amplification. Measured against a 72 GiB archive at 16 MiB pieces, a cold tile cost roughly 30
+seconds against a single peer.
+
+Overridable globally, per scheduled source, and per request — an archive nobody will read
+randomly can keep larger pieces. Note that piece size has little bearing on load imposed on
+network equipment: peers request 16 KiB blocks whatever the piece size. The setting that
+matters there is `maxConnections`, since every peer holds a NAT table entry. See
+[docs/publishing.md](docs/publishing.md).
+
+## API
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/status` | Engine health, counts, watched folders, subscriptions |
+| `GET` | `/api/torrents` | Catalog joined with live swarm state |
+| `POST` | `/api/torrents` | Add via `{path}`, `{url}`, `{magnet}`, `{torrentUrl}`, or a raw `.torrent` body |
+| `DELETE` | `/api/torrents/:infoHash` | Remove (`?deleteData=true` to delete data too) |
+| `GET` | `/api/torrents/:infoHash/file` | Download the `.torrent` |
+| `GET` | `/api/torrents/:infoHash/magnet` | Magnet URI |
+| `GET` | `/api/torrents/:infoHash/peers` | Per-peer detail |
+| `POST` | `/api/torrents/:infoHash/check` | Has the source changed since the torrent was made? |
+| `POST` | `/api/torrents/:infoHash/rebuild` | Rebuild from the current source (mints a new infohash) |
+| `POST` | `/api/check-origins` | Check every archive with a watchable source |
+| `POST` | `/api/adopt` | Import what the engine already holds |
+| `POST` | `/api/subscriptions/refresh` | Poll subscribed feeds now |
+| `GET` | `/feed.xml`, `/feed/:category.xml` | RSS |
+
+## Status
+
+Working and verified end to end against a live 71.93 GiB OpenMapTiles archive: torrent creation,
+joining existing torrents, catalog persistence, map metadata extraction, category feeds, live
+swarm stats, and cache mode holding at zero bytes on disk.
+
+Not yet exercised: the qBittorrent engine against a real instance, watch-folder imports, feed
+subscription round-trips between two nodes, and BEP 46 publish/resolve against a live DHT (the
+crypto and magnet handling are tested; interop with libtorrent's encoding is not).
+
+## License and attribution
+
+BSD-3-Clause. Third-party notices in [NOTICE.md](NOTICE.md).

package/docs/architecture-diagram.md

@@ -0,0 +1,287 @@
+# Architecture Diagram — pmtiles-swarm
+
+How a map library is ingested once, distributed over BitTorrent, and served to
+both ordinary and torrent-aware clients from the same URLs.
+
+Four views: **the whole topology**, **how a tile request resolves**, **what a
+torrent-aware client does differently**, and **what happens when an archive is
+updated**.
+(Renders in VS Code's Markdown preview and on GitHub.)
+
+---
+
+## 1. Topology
+
+One node publishes, any number serve, everything meets in the swarm.
+
+**"Primary" and "secondary" are roles, not node types.** The only thing that makes
+a node primary is that it creates torrents and owns the catalog others subscribe
+to. It can sit in the load-balanced pool alongside everything else — it holds
+complete copies, so it is the *best* tile server in the fleet, not an exception
+to it. The diagram separates them only to keep the arrows legible.
+
+Likewise **mirror and cache are per-archive choices, not node identities.** A
+serving node can mirror the archives it cares about and cache the rest. Mirroring
+everything is a perfectly good deployment: every node seeds fully, every node
+reads locally, and cache mode is there for the nodes and archives where a full
+copy is not worth the disk.
+
+```mermaid
+%%{init: {"flowchart": {"rankSpacing": 80, "nodeSpacing": 50}}}%%
+graph LR
+    subgraph IN["Ingest — any of four ways"]
+        F1["watch folder<br/><small>new .pmtiles appears</small>"]
+        F2["scheduled source<br/><small>protomaps, mapterhorn…</small>"]
+        F3["torrent / magnet URI<br/><small>join an existing swarm</small>"]
+        F4["local file or HTTP URL<br/><small>hashed into a new torrent</small>"]
+    end
+
+    F1 & F2 & F3 & F4 --> PRI
+
+    PRI["<b>pmtiles-swarm · publisher</b><br/>creates torrents · owns the catalog<br/>publishes /feed.xml<br/><small>mirrors — and can serve tiles too</small>"]
+
+    PRI -->|"RSS<br/>torrents + magnets"| S1 & S2 & S3
+
+    subgraph SEC["Serving tier — subscribed to the publisher's feed"]
+        S1["pmtiles-swarm<br/><small>mirror — reads locally, seeds fully</small>"]
+        S2["pmtiles-swarm<br/><small>mirror — reads locally, seeds fully</small>"]
+        S3["pmtiles-swarm<br/><small>cache — reads pieces on demand</small>"]
+    end
+
+    BT{{"BitTorrent swarm<br/><small>DHT · trackers · web seeds</small>"}}
+
+    PRI <==>|"seeds"| BT
+    S1 & S2 <==>|"seed complete copies"| BT
+    S3 <==>|"pull pieces on demand<br/>seed back what it holds"| BT
+
+    PRI --> LB
+    S1 & S2 & S3 --> LB["Load balancer / CDN<br/>HAProxy · Cloudflare<br/><small>caches tiles — they are immutable</small>"]
+
+    LB --> C1 & C2
+
+    subgraph CL["Clients"]
+        C1["<b>Torrent-aware client</b><br/>maplibre-maui-ac<br/><small>reads the torrent block,<br/>joins the swarm directly</small>"]
+        C2["<b>Ordinary client</b><br/>maplibre-gl-js · Leaflet<br/><small>ignores the torrent block,<br/>fetches tiles over HTTP</small>"]
+    end
+
+    C1 <==>|"tiles from pieces"| BT
+
+    %% 4-6 = RSS distribution, 7-10 and 17 = BitTorrent, rest = HTTP
+    linkStyle 4,5,6 stroke:#3F8F4F,stroke-width:2.5px;
+    linkStyle 7,8,9,10,17 stroke:#F5A623,stroke-width:3.5px;
+```
+
+**Key points:** **orange = BitTorrent, green = RSS distribution, plain = HTTP.**
+The publisher is the only node that *creates* torrents; the rest learn about
+archives from its feed and join the swarm, each choosing per archive whether to
+mirror it or cache it.
+
+Every node is both a reader and a seeder. A mirror seeds the whole archive; a
+cache-mode node seeds whatever pieces it has pulled to answer requests. Either
+way serving load turns into swarm capacity rather than consuming it, which is the
+inversion that makes this worth building.
+
+The publisher is a single point of failure for **publishing new archives only**.
+Once a torrent exists, the swarm and the serving tier keep working without it —
+including the feed's existing items, which subscribers have already acted on.
+
+---
+
+## 2. How a tile request resolves
+
+The same URL takes very different paths depending on who asks and what the
+answering node holds.
+
+```mermaid
+%%{init: {"flowchart": {"rankSpacing": 55, "nodeSpacing": 40}}}%%
+graph TD
+    REQ["GET /archives/{infohash}/{z}/{x}/{y}.pbf"] --> CDN{"CDN cache?"}
+    CDN -->|"hit"| DONE(["tile bytes"])
+    CDN -->|"miss"| NODE["a secondary, via the load balancer"]
+
+    NODE --> HOLD{"does this node hold<br/>a complete copy?"}
+    HOLD -->|"yes · mirror"| LOCAL["read the local file<br/><small>NodeFileSource</small>"]
+    HOLD -->|"no · cache mode"| ENG{"can the engine<br/>read pieces?"}
+
+    ENG -->|"libtorrent · webtorrent"| SWARM["map the byte range onto pieces<br/><small>TorrentSource</small>"]
+    ENG -->|"qBittorrent"| ERR["501 — no piece-level read"]
+
+    SWARM --> PC{"piece cached?"}
+    PC -->|"yes"| LOCAL
+    PC -->|"no"| FETCH["fetch the piece<br/><small>web seed, or peers</small>"]
+    FETCH --> SEED["keep it · seed it back"]
+    SEED --> LOCAL
+
+    LOCAL --> DONE
+
+    %% 10-12 = the piece fetch and seed-back path
+    linkStyle 10,11,12 stroke:#F5A623,stroke-width:3px;
+```
+
+**Key points:** a cold tile on a cache-mode node costs one piece fetch — and a
+**web seed answers that in well under a second**, against 30+ seconds for a cold
+swarm-only fetch. If your archives are also on plain HTTP storage, put that URL
+in the torrent's `url-list`; it is the single biggest lever on this whole design.
+
+A node holding a complete copy skips all of this and reads its local file.
+
+---
+
+## 3. What a torrent-aware client does
+
+The server-side path above is what an *ordinary* client triggers. A torrent-aware
+client does something different: it takes over the archive reading itself, and
+stops needing the tile endpoint at all.
+
+The important part is that it does both at once — HTTP for the first paint, swarm
+in the background — so there is never a blank map waiting for metadata.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant App as Map (maplibre)
+    participant P as Plugin
+    participant HTTP as pmtiles-swarm<br/>(via CDN)
+    participant BT as BitTorrent swarm
+
+    App->>P: load style → tiles.json
+    P->>HTTP: GET /archives/{hash}/tiles.json
+    HTTP-->>P: TileJSON + torrent block
+
+    Note over P: claims the /archives/{hash}/ prefix,<br/>so only these URLs come to it
+
+    par Map is usable immediately
+        App->>P: tile 12/2145/1436
+        P->>HTTP: GET …/12/2145/1436.pbf
+        HTTP-->>App: tile bytes
+    and Swarm warms up in the background
+        P->>BT: join (.torrent — metadata already in hand)
+        BT-->>P: connected
+        P->>BT: fetch PMTiles header + root directory
+        BT-->>P: those pieces
+        Note over P: now able to resolve any tile<br/>to a byte range locally
+    end
+
+    App->>P: tile 12/2146/1436
+    Note over P: tile → byte range (PMTiles directory)<br/>→ piece index
+    P->>BT: fetch that piece
+    BT-->>P: piece
+    P-->>App: tile bytes, no HTTP involved
+
+    Note over P,BT: the client is now a peer —<br/>it seeds those pieces back
+
+    App->>P: tile in an unfetched region
+    P->>BT: fetch piece
+    BT--)P: too slow / unavailable
+    P->>HTTP: fall back for this tile
+    HTTP-->>App: tile bytes
+```
+
+**Key points:** the plugin resolves tiles the same way the server does — PMTiles
+directory lookup, byte range, piece index — it just does it on the device. That
+is why the `torrent` block carries the archive's `.torrent` rather than per-tile
+URLs: **there is nothing tile-specific in the swarm.** The swarm holds one file,
+and both ends know how to read tiles out of it.
+
+Three consequences worth being clear about:
+
+- **HTTP is never fully abandoned.** It is the fallback for anything the swarm
+  cannot answer quickly, and the only path until the swarm is connected.
+- **The client becomes a seeder.** Every piece it pulls, it serves — so a popular
+  region gets *faster* as more clients view it, which is the opposite of how a
+  tile server behaves under load.
+- **Prefer the `.torrent` over the magnet.** A magnet carries only an infohash, so
+  the client must find peers and complete a metadata exchange before it knows
+  anything about the archive — measured at 90 to 240 seconds against a 72 GiB
+  archive. The `.torrent` served alongside the TileJSON already contains the
+  metadata and is ready immediately.
+
+---
+
+## 4. Updating an archive
+
+New data means a new infohash, which is what makes cache invalidation free.
+
+```mermaid
+%%{init: {"flowchart": {"rankSpacing": 60}}}%%
+graph LR
+    NEW["new planet.pmtiles<br/><small>weekly build</small>"] --> HASH["primary re-hashes<br/>→ new infohash"]
+    HASH --> BEP["BEP 46 mutable entry<br/><small>same public key, seq+1</small>"]
+    HASH --> FEED["new RSS item"]
+
+    BEP --> FOLLOW["clients following the key<br/>see the new version"]
+    FEED --> SUBS["secondaries add the new torrent"]
+
+    SUBS --> URLS["tiles.json now points at<br/>/archives/{new infohash}/…"]
+    URLS --> CACHE["old CDN entries simply<br/>stop being referenced<br/><small>no purge needed</small>"]
+
+    linkStyle 2,4 stroke:#3F8F4F,stroke-width:2.5px;
+```
+
+**Key points:** tile URLs are content-addressed, so they never need invalidating.
+The old infohash stays valid and servable for as long as anyone still holds it —
+useful for clients pinned to a known-good build — while new requests move to the
+new one as soon as they re-read `tiles.json`. The only mutable thing in the whole
+system is that one document.
+
+---
+
+## Deployment notes
+
+**Decide how absolute URLs get built.** TileJSON and the RSS feed both contain
+absolute URLs, and there are three ways to arrive at them:
+
+| Config | Behaviour | Use when |
+| --- | --- | --- |
+| `publicUrl` set | One canonical URL, whatever the request said | There is a single public name |
+| `trustProxy` set | Per request, from `X-Forwarded-Proto` and `X-Forwarded-Host` | One node answers on several names or schemes |
+| neither | From the connection itself | Direct access, no proxy |
+
+```json
+{
+  "trustProxy": "loopback, 10.0.0.0/8"
+}
+```
+
+`trustProxy` is what lets a single node serve **both** `https://maps.example.org`
+to the internet and `http://maps.internal` to the LAN, rewriting every published
+URL to match how the request arrived. It takes anything Express accepts: `true`,
+a hop count, or a subnet list. Prefer the subnet list — trusting these headers
+from an untrusted client lets it claim any host it likes, and that host ends up
+in documents you publish.
+
+Behind a TLS-terminating proxy with neither option set, the node advertises
+`http://` URLs, and a browser that loaded the map over `https` blocks every one
+as mixed content — which looks like an empty map rather than a misconfiguration.
+
+**Load balancing needs no session affinity.** Any node serving a given infohash
+returns byte-identical tiles, because the infohash pins the content. Round-robin
+is fine, and a node can be added or removed mid-request-stream without a client
+noticing.
+
+**Cold start only applies to cache-mode nodes.** A node holding a complete copy
+reads its local file and is fast from the first request. If every serving node
+mirrors, this section does not apply to you at all.
+
+Where nodes *do* run in cache mode, each warms its own piece cache, so scattering
+requests for one region across N nodes costs N first-fetches rather than one.
+Three things reduce that, in order of effect:
+
+1. **The CDN absorbs repeats.** Tiles are immutable, so the second request for a
+   tile never reaches any node.
+2. **The nodes are peers in the same swarm.** A node fetching a piece a sibling
+   already holds gets it *from that sibling*, usually over the LAN. Local service
+   discovery is on by default, so same-subnet nodes find each other without
+   configuration. The cost is one external fetch plus N−1 local ones, not N
+   external ones.
+3. **Warm before rotating in.** `POST /api/torrents/{infohash}/warm` pre-fetches
+   a region so the first real request is never the slow one. See
+   [serving tiles](serving-tiles.md#warming-a-region).
+
+Path-based affinity (HAProxy's `balance uri`) helps too, but it is the smallest
+of the four levers and it costs you even load distribution.
+
+**Size cache-mode disks for what gets viewed, not for the archive.** Cache usage
+grows with what people actually look at and is not bounded on its own. Watch it,
+and mirror instead where a full copy is affordable — a mirror is predictable,
+faster, and a better peer.