pmtiles-swarm 0.31.0 → 0.32.1

package/CHANGELOG.md

@@ -7,6 +7,50 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.32.1
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+### 🐞 Bug fixes
+- **Requires pmtiles-torrent 0.5.1, so the connection indicator and Recheck files actually work.**
+  Both features shipped against a dependency range that still allowed 0.4.6, which has neither
+  sidecar op. The declared requirement and the declared dependency disagreed, and the symptom was
+  a feature that looked built and did nothing: the indicator hid itself, because an engine that
+  cannot answer is deliberately not reported as unreachable, so there was nothing to see and
+  nothing to explain why.
+
+- _...Add new stuff here..._
+
+## 0.32.0
+### ✨ Features and improvements
+- _...Add new stuff here..._
+
+### 🐞 Bug fixes
+- **A mutable magnet no longer carries a web seed.** A `ws=` URL names one build; a BEP 46 magnet
+  names a series. They disagree the moment the next build is published — and not harmlessly, which
+  was the part that was easy to miss. `tr=` and `ws=` live outside the info dictionary, so BEP 9
+  never replaces them: a client keeps the magnet's copies and merges them into whatever torrent it
+  resolved to. So the client that did exactly what the magnet asked — resolved the key, landed on
+  the current build — was handed a web seed for a previous one, and every piece it fetched from
+  there failed hash verification until the peer banned it. A client that *ignored* the key and
+  joined the pinned `xt=` was fine, because there the infohash and the web seed named the same
+  build.
+
+  Nothing is lost. The metainfo carries the right web seed for whichever build was actually
+  resolved, written into `url-list` when that torrent was created, and there are two ways to reach
+  it: the `torrent=` handle added to style URLs in 0.30.0, or BEP 9 from any peer. The magnet was
+  the third route and the only one that could be wrong.
+
+  Affects the category style URL, the feed's `pmtiles:mutable`, the TileJSON `torrent.mutable
+  .magnet` and the publisher's own magnet. Archives' immutable magnets still carry their web seeds,
+  since there `xt` and `ws` cannot drift apart. The parameter was removed from `mutableMagnet`
+  outright rather than dropped at each call site, so it cannot be reintroduced by a future caller.
+
+  **Restyle anything holding one.** A style carrying an older mutable magnet keeps working, but
+  carries the stale web seed until it is regenerated.
+
+- _...Add new stuff here..._
+
 ## 0.31.0
 ### ✨ Features and improvements
 - **A Recheck files button, for when an archive's progress and its files disagree.** Every figure a

package/docs/serving-tiles.md

@@ -303,7 +303,7 @@ 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=…
+magnet:?xs=urn:btpk:<public key>&s=openmaptiles&dn=…
 ```
 
 No infohash anywhere, so nothing to go stale. A client resolves the record over
@@ -368,7 +368,7 @@ TileJSON documents from this server carry a non-standard `torrent` member:
       "publicKey": "7680dc95248eb807…",
       "salt": "openmaptiles",
       "seq": 1786108931,
-      "magnet": "magnet:?xs=urn:btpk:7680dc95248eb807…&s=openmaptiles&ws=…"
+      "magnet": "magnet:?xs=urn:btpk:7680dc95248eb807…&s=openmaptiles"
     }
   }
 }

package/docs/tilejson.md

@@ -77,13 +77,28 @@ serve this block — publishing is the only thing the secret is used for.
 `mutable.magnet` carries **both** identifiers:
 
 ```
-magnet:?xt=urn:btih:<current build>&xs=urn:btpk:<public key>&dn=…&s=…&ws=…
+magnet:?xt=urn:btih:<current build>&xs=urn:btpk:<public key>&dn=…&s=…
 ```
 
 - `xs=urn:btpk:` is the public key. Resolving it through the DHT gives whichever
   infohash is current, now and after every future rebuild.
 - `xt=urn:btih:` is the build that was current when the document was generated.
 
+**No `ws=`, and the omission is deliberate.** A web seed URL names one build;
+this magnet names a series. They disagree the moment the next build is
+published, and not harmlessly: `tr=` and `ws=` sit outside the info dictionary,
+so BEP 9 never replaces them — a client keeps the magnet's copies and merges
+them into whatever torrent it resolved to. A web seed attached to a build it
+does not describe fails hash verification on every piece it serves, until the
+peer banning it stops the waste.
+
+Nothing is lost by leaving it out. `webseeds` above is the same list for the
+build this document describes, and the metainfo for whichever build a client
+resolves to carries its own — written into `url-list` when that torrent was
+created, and reachable either from the `torrent=` handle in a style fragment or
+over BEP 9 from any peer. The archive's own immutable magnet still carries web
+seeds, because there `xt` and `ws` name the same build and cannot drift apart.
+
 A client reads whichever it understands. A DHT-capable one resolves the key and
 follows the series indefinitely; one without a DHT joins the infohash and gets a
 working archive immediately.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "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",
@@ -46,7 +46,7 @@
     "maplibre-gl": "^6.2.0",
     "parse-torrent": "^11.0.24",
     "pmtiles": "^4.4.1",
-    "pmtiles-torrent": "^0.4.6",
+    "pmtiles-torrent": "^0.5.1",
     "webtorrent": "^3.0.21"
   },
   "engines": {

package/src/api.js

@@ -123,7 +123,6 @@ function styleUrlFor(category, newest, base) {
         salt: newest.mutable.salt ?? category,
         // The category, since that is what this magnet resolves to.
         name: newest.mutable.salt ?? category,
-        webSeeds: newest.webSeeds,
       })
     : newest?.magnet;
   // Category-scoped rather than the newest build's immutable URL, for the same

package/src/feed.js

@@ -147,7 +147,6 @@ ${
           infoHash: entry.infoHash,
           salt: entry.mutable.salt,
           name: entry.mutable.salt ?? entry.name,
-          webSeeds: entry.webSeeds,
         }),
       )}</pmtiles:mutable>`
     : ''

package/src/mutable.js

@@ -86,7 +86,6 @@ function rawPublicKey(publicKey) {
  * @param {string} [options.infoHash] - The build that is current, so a client with no DHT has somewhere to start.
  * @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.
  */
@@ -129,12 +128,25 @@ export function mutableMagnet(publicKey, options = {}) {
   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)}`);
-  }
+  // No `ws=`, and the omission is the point.
+  //
+  // A web seed URL names one build. This magnet names a series, and a client
+  // that resolves the key lands on whatever build is current -- so the two
+  // disagree the moment the next one is published. They do not disagree
+  // harmlessly: `tr=` and `ws=` live outside the info dictionary, so BEP 9
+  // never replaces them, and a client keeps the magnet's copies and merges
+  // them into whatever torrent it ends up with. The result is a web seed
+  // attached to a build it does not describe, failing hash verification on
+  // every piece it serves until the peer bans it.
+  //
+  // Nothing is lost. The metainfo carries the right web seed for whichever
+  // build the client actually resolved -- it is written into `url-list` when
+  // that build's torrent is created -- and there are two ways to reach it: the
+  // `torrent=` handle in the style fragment, or BEP 9 from any peer. This was
+  // the third route, and the only one that could be wrong.
+  //
+  // An immutable magnet is a different case and still carries its web seeds:
+  // there, `xt` and `ws` name the same build and cannot drift apart.
   return parts.join('&');
 }
 

package/src/publisher.js

@@ -211,7 +211,6 @@ export class MutablePublisher {
       // with the metadata and overrides it -- so nothing depends on this
       // beyond being honest about what the magnet identifies.
       name: category,
-      webSeeds: entry?.webSeeds,
     });
   }
 

package/src/tilejson.js

@@ -113,7 +113,6 @@ function buildTorrentBlock(entry, root) {
         // The category, not this build: the record resolves to whichever
         // archive is current, and `dn` is a label the metadata replaces.
         name: entry.mutable.salt,
-        webSeeds: entry.webSeeds,
       }),
     };
   }