pmtiles-swarm 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -7,6 +7,65 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.13.1
+### 🐞 Bug fixes
+- **A node with a secondary engine no longer takes a quarter of an hour to start listening.**
+  Handing an archive to a second seeding client makes it hash every byte before it will serve any
+  — minutes for tens of gigabytes — and that hand-over was **awaited** inside `add()`. On startup,
+  where the library is restored one archive at a time, the cost landed end to end before the node
+  would bind its port. A seventeen-archive library sat silent for about fifteen minutes.
+
+  The hand-over is now queued and the caller carries on. Nothing depended on waiting for it: the
+  periodic sweep that already exists to catch archives finishing later is the same mechanism, and
+  a failed hand-over already un-marks itself so that sweep retries it.
+
+  Queued through one chain rather than fired off freely, so hand-overs still run one at a time —
+  seventeen archives hashing at once on a spinning disk is slower than seventeen in turn, and much
+  harder to reason about.
+- **Restoring a large library reports progress.** It said nothing at all until it had finished, so
+  a node that was working and a node that was stuck looked identical for as long as it took — long
+  enough, on a real library, to go looking for a debugger:
+
+  ```
+  [restore] 6 of 17 after 15s
+  ```
+
+  On a timer rather than per archive, so a small library stays quiet.
+
+## 0.13.0
+### ✨ Features and improvements
+- **The publisher's DHT socket is bound explicitly, on a configurable port.** It was left to bind
+  implicitly on its first send, which works but takes an unpredictable ephemeral port and reports
+  nothing — so there was no way to forward it, and no way to tell which one it had. `mutable.dhtPort`
+  now sets it (`0`, ephemeral, by default) and the port is logged at startup.
+
+  Publishing needs no forward either way: a put is outbound, and the replies come back on the same
+  socket the way any UDP client's do. Pinning and forwarding one makes this a *reachable* DHT node
+  instead, which earns a better routing table and contributes back — worth having on a node that
+  runs continuously.
+
+  It must not collide with an engine's port. Each seeding engine runs a DHT of its own, so a node
+  with both has three UDP participants and only this one is placed here; two sockets cannot hold
+  one port and the node would fail to start.
+
+### 📚 Documentation
+- **[docs/running-as-a-service.md](docs/running-as-a-service.md) covers the publisher key**:
+  generating it as the service account so ownership is right, `chmod 400` because nothing ever
+  writes it back, and why it must be backed up off the machine — losing it breaks every style
+  pointing at that public key, permanently, with no reissue. Also what happens under HA config
+  sync: the configuration replicates to the standby and the key does not, so the standby logs
+  `not publishing: ENOENT` and serves on, which is the intended outcome rather than a fault. And
+  how to confirm it works, including that `nodes: 0` in the log means nobody stored the record
+  however healthy the rest of the line looks.
+- **The ports table lists the DHT port**, which had only been described in the publisher section —
+  not where anyone looks when deciding what to forward.
+- **Why publishing does not reuse an engine's DHT** is recorded in
+  [src/publisher.js](src/publisher.js), since it will be asked again. libtorrent's is unreachable:
+  the 2.x Python bindings expose neither `dht_put_item` nor `dht_get_item`, though the alerts are
+  bound, so the C++ side supports BEP 44 and there is simply no method to call. WebTorrent's *is*
+  `bittorrent-dht` and could be reused to save a socket; that is a deliberate choice rather than an
+  oversight, taken to keep one code path that behaves the same whichever engine is configured.
+
 ## 0.12.0
 ### ✨ Features and improvements
 - **A category can now be addressed without a server at all.** A node that builds can publish a

package/docs/architecture-diagram.md

@@ -224,7 +224,7 @@ New data means a new infohash, which is what makes cache invalidation free.
 %%{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 --> BEP["BEP 46 mutable entry<br/><small>same public key, new seq</small>"]
     HASH --> FEED["new RSS item"]
 
     BEP --> FOLLOW["clients following the key<br/>see the new version"]
@@ -239,8 +239,36 @@ graph LR
 **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.
+new one as soon as they re-read `tiles.json`.
+
+**There are exactly two mutable things**, and they say the same thing by
+different means: the `/latest/<category>/` documents, which need this server, and
+the BEP 46 record, which does not. A style pointing at the public key resolves
+the current build over the DHT with nothing of ours running at all. Only the node
+that builds signs those records — see
+[security.md](security.md#the-publisher-key-is-not-a-credential), because the key
+behaves unlike every other secret in the system.
+
+The sequence number is derived from the clock rather than incremented, so a
+publisher that is rebuilt or restored from backup carries on without needing to
+remember where it had got to.
+
+### Bootstrapping without the server
+
+A torrent-aware client still has to *learn* the magnet from somewhere, and until
+it does, the swarm — the part that depends on no server — is unreachable
+precisely when the server is down. The fix is that the magnet travels in the
+**fragment** of the TileJSON URL a style already carries:
+
+```
+https://swarm.example.org/latest/openmaptiles/tiles.json#magnet:?xs=urn:btpk:…&s=openmaptiles&ws=…
+```
+
+A fragment is never sent in an HTTP request, so ordinary clients fetch the
+TileJSON and ignore it while a swarm-aware one reads the magnet before making any
+call. With a BEP 46 key in it (`xs=urn:btpk:`) rather than an infohash, that
+string does not go stale on the next build either. See
+[serving-tiles.md](serving-tiles.md#a-fragment-that-survives-a-rebuild).
 
 ---
 

package/docs/running-as-a-service.md

@@ -354,6 +354,116 @@ What the running service actually has:
 systemctl show -p ReadWritePaths -p UMask -p SupplementaryGroups pmtiles-swarm
 ```
 
+## The publisher key
+
+Only needed if this node publishes BEP 46 records — the signed DHT entries that
+let a style point at a category rather than at a build that goes stale. Skip
+this section entirely if it does not build archives.
+
+**Generate it as the service account**, so the file is owned by the user that
+has to read it:
+
+```sh
+sudo -u pmtiles-swarm -H /var/lib/pmtiles-swarm/node_modules/.bin/pmtiles-swarm   publisher-key > /etc/pmtiles-swarm/publisher.pem
+sudo chown pmtiles-swarm:pmtiles-swarm /etc/pmtiles-swarm/publisher.pem
+sudo chmod 400 /etc/pmtiles-swarm/publisher.pem
+```
+
+The PEM goes to stdout and the public key to stderr, so the redirect above
+captures only the key material and you still see the public half on the
+terminal. Write that public key down — it is what subscribers point at, and it
+is the one part you will want later.
+
+`400` rather than `600`: the service only ever reads this. Nothing in the
+product writes it back, so removing write permission costs nothing and means a
+compromised process cannot quietly replace it.
+
+Then in `/etc/pmtiles-swarm/swarm.config.json`:
+
+```json
+{
+  "mutable": {
+    "publish": true,
+    "keyPath": "/etc/pmtiles-swarm/publisher.pem"
+  }
+}
+```
+
+`/etc/pmtiles-swarm` is already in `ReadWritePaths` because the console rewrites
+the configuration there, so the unit needs no change.
+
+### Back it up, off this machine
+
+Losing this file breaks **every style pointing at that public key, permanently**
+— there is no recovery, no reissue, and no way to prove to a subscriber that a
+new key is you. It is not like an API key you can rotate.
+
+Back it up somewhere that is not this disk, and treat the backup as seriously as
+the original: whoever holds it can publish a signed record telling your
+subscribers that any archive is the current build, and clients will believe it
+because the signature checks out.
+
+### Exactly one publisher
+
+Two nodes publishing under one key fight over the sequence number, each
+overwriting the other's claim about what is current. So the PEM belongs on the
+build node and nowhere else.
+
+**This matters if you run HA config sync.** The configuration will replicate to
+the standby, `publish: true` and all — but the PEM will not, because you are
+not going to copy it. The standby then logs
+
+```
+[mutable] not publishing: ENOENT: no such file or directory
+```
+
+on every start and carries on serving normally. That is the intended outcome
+rather than a fault: the config syncing is harmless, and the key not syncing is
+the point. If the noise bothers you, set `mutable.publish` to `false` in the
+standby's config after the sync.
+
+### It does not need a port forwarded
+
+The DHT socket is separate from the seeding engine's, and by default takes an
+ephemeral UDP port (`mutable.dhtPort: 0`). That is enough to publish: a put is
+outbound — find nodes, then send — and the replies come back on the same
+socket the way any UDP client's do, which NAT handles without help.
+
+Setting a fixed port and forwarding it makes this a *reachable* DHT node, which
+means better lookups and contributing back to the network. Worth doing if this
+node is long-lived, but nothing here requires it.
+
+**Do not reuse the libtorrent engine's port.** That engine runs a DHT of its own
+on `libtorrent.listen`, and two sockets cannot hold one port — the node would
+fail to start.
+
+The port in use is reported at startup:
+
+```
+[mutable] DHT on UDP 63213
+```
+
+### Confirming it works
+
+```sh
+journalctl -u pmtiles-swarm | grep mutable
+```
+
+A healthy publisher says which categories it is announcing and under which key
+at startup, then one line per category whenever a build moves:
+
+```
+[mutable] publishing 3 categories as 7680dc95248eb807… every 30m
+[mutable] openmaptiles -> 4813a0e68e4b (seq 1786108931, 8 nodes)
+```
+
+`nodes` is how many DHT peers stored the record. **Zero means nobody did**, and
+the record does not exist however healthy the log looks otherwise — check that
+UDP is not blocked and that the DHT is reachable.
+
+The first publish waits about fifteen seconds after start, because a put into a
+DHT that has not finished bootstrapping reaches nobody.
+
 ## The sidecar
 
 The libtorrent engine runs Python as a child process, so the service user needs
@@ -373,16 +483,33 @@ rather than exiting. Name the interpreter explicitly when the service user's
 
 ## Ports
 
-Four listeners, and only the peer ports want a firewall rule. See
+Five listeners, and only the peer ports want a firewall rule. See
 [ports and reachability](engines.md#ports-and-reachability) for the detail.
 
 | | |
 | --- | --- |
 | `libtorrent.listen` — 6881, TCP and UDP | forward it |
 | `webtorrent.clientOptions.torrentPort` — pin it, or it changes every start | forward it |
+| `mutable.dhtPort` — UDP, ephemeral by default | optional; see below |
 | `port` — 8090 | your proxy or CDN |
 | `adminPort` — 8091, bound to `127.0.0.1` | nothing; that is the point |
 
+`mutable.dhtPort` is the odd one. Publishing works without any forward, because
+a put is outbound and the replies come back on the same socket the way any UDP
+client's do. Pin it and forward it only if you want this to be a *reachable*
+DHT node — which earns a better routing table and contributes back, and is
+worth having on a node that runs continuously.
+
+Pin it to something free: **not** `libtorrent.listen`, which is a DHT of its
+own, and not `torrentPort`. `6883` sits clear of both.
+
+```json
+{ "mutable": { "dhtPort": 6883 } }
+```
+
+Note that each engine runs its own DHT as well, so a node with both engines has
+three UDP participants. Only this one is yours to place.
+
 ## Updating
 
 ```sh

package/docs/security.md

@@ -188,6 +188,56 @@ Three ways past it, in order of preference:
 2. Bind to `127.0.0.1` and reach it through a reverse proxy that authenticates.
 3. Set `allowUnauthenticated: true`, if the network really is trusted.
 
+## The publisher key is not a credential
+
+Everything above guards *this node*: who may read the API, who may change
+settings, who may add an archive. The publisher key is a different kind of
+secret, and the difference is worth stating plainly because the habits do not
+carry over.
+
+`mutable.keyPath` holds an ed25519 private key used to sign BEP 46 records — the
+DHT entries that say which archive is the current build of a category. It is a
+**signing key**, closer to a code-signing certificate than to an API token.
+
+| | An access credential (`apiKey`, a token, `password`) | The publisher key |
+| --- | --- | --- |
+| What it grants | access to one node | authority over what your subscribers believe |
+| If it leaks | that node is compromised | anyone can sign a record pointing your subscribers at any archive |
+| If you lose it | mint another | every style pointing at that public key breaks, permanently |
+| Rotation | revoke and reissue | there is none |
+
+That third row is the one people are unprepared for. A public key **is** the
+identity: there is no registry to update and no way to tell a subscriber that a
+new key is also you. Losing the file ends that identity.
+
+And the second row is why it does not belong on a serving tier. A leaked API key
+lets someone read a node. A leaked publisher key lets someone tell every
+subscriber that an archive they control is your latest planet build — signed,
+verifying correctly, and indistinguishable from a real announcement.
+
+**So it lives on exactly one machine.** Only the node that builds needs it;
+serving nodes carry the public half on the catalog entry and hand it out in the
+TileJSON, which is why a serving tier can be compromised without anyone being
+able to publish. Running two publishers under one key is separately a mistake:
+they fight over the sequence number.
+
+Practically:
+
+- `chmod 400`, owned by the service account. Nothing in the product writes it
+  back, so it does not need to be writable and should not be.
+- Back it up **off the machine**, and treat the backup as seriously as the
+  original.
+- Do not put it in an image, a config-sync set, or anywhere a standby will
+  receive it. Under HA sync the configuration replicates and the key does not,
+  which is the intended asymmetry rather than an oversight — the standby logs
+  `not publishing: ENOENT` and serves normally.
+- It is unrelated to `auth`. Turning authentication off does not expose it, and
+  rotating the API key does not affect it.
+
+Generate one with `pmtiles-swarm publisher-key`. Setup detail is in
+[running-as-a-service.md](running-as-a-service.md#the-publisher-key); what it is
+*for* is in [serving-tiles.md](serving-tiles.md#a-fragment-that-survives-a-rebuild).
+
 ## What this is not
 
 **It is not a defence against someone on your network.** Sessions are bearer

package/docs/serving-tiles.md

@@ -291,7 +291,13 @@ TileJSON documents from this server carry a non-standard `torrent` member:
     "torrent": "https://swarm.example.org/archives/913d…/archive.torrent",
     "name": "planet.pmtiles",
     "size": 77242531840,
-    "webseeds": ["https://maps.example.org/planet.pmtiles"]
+    "webseeds": ["https://maps.example.org/planet.pmtiles"],
+    "mutable": {
+      "publicKey": "7680dc95248eb807…",
+      "salt": "openmaptiles",
+      "seq": 1786108931,
+      "magnet": "magnet:?xs=urn:btpk:7680dc95248eb807…&s=openmaptiles&ws=…"
+    }
   }
 }
 ```
@@ -309,10 +315,29 @@ load it. That also means a torrent-aware client gets a working map immediately
 over HTTP while the swarm is still finding peers, rather than staring at an empty
 canvas for the 90 to 240 seconds a cold magnet can take to resolve metadata.
 
-For an archive published as a mutable torrent, the block also carries
-`mutable.publicKey`, so a client that understands BEP 46 can follow updates
-rather than pinning to the version the document was generated from. See
-[publishing](publishing.md).
+### The `mutable` sub-block
+
+Present only when a publisher is announcing this archive's category over the
+DHT. It is the difference between a document describing *this build* and one
+describing *the current build*:
+
+| | |
+| --- | --- |
+| `publicKey` | The identity to resolve against. Public — there is nothing secret in the block |
+| `salt` | The category, so one key can address several |
+| `seq` | The sequence of the record this document was generated beside |
+| `magnet` | Assembled from the above, ready to paste into a style's URL fragment |
+
+`magnet` is built rather than left to the consumer because every node can build
+it — it contains only the public half — so a fleet behind a balancer hands out
+one identical string and none of them can publish. A BEP 46 client resolves it
+and follows updates rather than pinning to the build this document happened to
+describe.
+
+See [a fragment that survives a rebuild](#a-fragment-that-survives-a-rebuild)
+above for how it reaches a style, and
+[security.md](security.md#the-publisher-key-is-not-a-credential) for why the
+private half lives on exactly one machine.
 
 ## Health checks
 
@@ -564,6 +589,13 @@ first tile can be seconds away.
 **Raster archives get the raster.** There is nothing to inspect in an image, so
 the panel says so and the map is for checking coverage.
 
+**What it has actually served** is on the archive's detail, as `served`, and
+across the node at `GET /api/stats` — requests, bytes, a breakdown by zoom and
+status, and which client addresses asked. Worth reading beside `reading`: an
+archive being read through the swarm while serving thousands of tiles is a
+different situation from one doing neither. See the
+[README](../README.md#seeing-what-a-node-is-actually-serving).
+
 No symbol layers are drawn and no glyphs are configured, deliberately: an
 archive carries tiles, not fonts, and a preview that needed a font server to
 render would not be a preview of the archive.

package/package.json

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

package/src/config.js

@@ -425,6 +425,19 @@ const DEFAULTS = {
     keyPath: undefined,
     /** How often to republish, in seconds. */
     republishSeconds: 1800,
+    /**
+     * UDP port for this node's DHT socket. 0 takes an ephemeral one.
+     *
+     * Publishing does not need a forwarded port: a put is outbound, and the
+     * replies come back on the same socket the way any UDP client's do, which
+     * NAT handles. Setting a fixed port and forwarding it makes this a
+     * reachable DHT node, which gives better lookups and contributes back —
+     * but nothing here requires it.
+     *
+     * Do not reuse the libtorrent engine's port. That engine runs a DHT of its
+     * own, and two sockets cannot hold one port.
+     */
+    dhtPort: 0,
   },
   /**
    * What this node has served, at `GET /api/stats`.

package/src/engines/composite.js

@@ -36,6 +36,8 @@ export class CompositeEngine {
   #timer;
   /** Infohashes handed to secondaries, so they are not handed over twice. */
   #shared = new Set();
+  /** Serialises background hand-overs, so they never run all at once. */
+  #shareChain = Promise.resolve();
   /** Set once a stop has begun, so late timers do nothing. */
   #stopping = false;
 
@@ -133,12 +135,54 @@ export class CompositeEngine {
     const infoHash = await this.#primary.add(request);
 
     if (this.#shareable(request) && (await this.#primaryHasItAll(infoHash))) {
-      await this.#shareOne(infoHash, request);
+      // Queued rather than awaited. Handing an archive to a seeding client it
+      // has not seen before makes it hash every byte first, which is minutes
+      // for tens of gigabytes -- so awaiting it here put that cost inside the
+      // caller. On startup, where the library is restored one archive at a
+      // time, that meant a node sat silent for a quarter of an hour before it
+      // would listen, doing work the periodic sweep exists to do anyway.
+      //
+      // Serialised through one chain rather than fired off freely: seventeen
+      // archives hashing at once on a spinning disk is slower than seventeen
+      // in turn, and far harder to reason about.
+      this.#queueShare(infoHash, request);
     }
 
     return infoHash;
   }
 
+  /**
+   * Resolves once every queued hand-over has finished.
+   *
+   * Nothing in normal operation waits for this — that is the point of the
+   * queue — but a caller that wants to observe the result, a test above all,
+   * needs somewhere to wait rather than a guess about microtask order.
+   * @returns {Promise<void>} - Resolves when the queue is empty.
+   */
+  async whenShared() {
+    // Awaited twice: the first await settles what is queued now, and anything
+    // that queued more while it ran is picked up by the second.
+    await this.#shareChain;
+    await this.#shareChain;
+  }
+
+  /**
+   * Runs a share after any already queued, without making the caller wait.
+   * @param {string} infoHash - The archive.
+   * @param {object} request - The original add request.
+   * @returns {void}
+   */
+  #queueShare(infoHash, request) {
+    this.#shareChain = this.#shareChain
+      .then(() => (this.#stopping ? undefined : this.#shareOne(infoHash, request)))
+      // #shareOne already swallows an engine refusing the archive; this is the
+      // last resort, so one failure cannot break the chain for everything
+      // queued behind it.
+      .catch((error) =>
+        console.warn(`[engine] could not hand over ${infoHash}: ${error.message}`),
+      );
+  }
+
   /**
    * Whether the primary actually holds the whole archive.
    *

package/src/index.js

@@ -273,6 +273,15 @@ PMTILES_SWARM_PUBLIC_URL
       ]);
       const pem = await fs.readFile(config.mutable.keyPath, 'utf8');
       const dht = new DHT();
+      // Bound explicitly rather than left to bind implicitly on first send,
+      // so the port is predictable and can be forwarded if you want this to
+      // be a reachable DHT node. 0 takes an ephemeral one, which is all
+      // publishing needs.
+      await new Promise((resolve, reject) => {
+        dht.once('error', reject);
+        dht.listen(config.mutable.dhtPort ?? 0, resolve);
+      });
+      console.log(`[mutable] DHT on UDP ${dht.address().port}`);
       publisher = new MutablePublisher({
         catalog,
         dht,

package/src/library.js

@@ -1463,9 +1463,41 @@ export class Library {
    */
   async restore() {
     const entries = this.#catalog.list();
-    let restored = 0;
-    let failed = 0;
+    const tally = { restored: 0, failed: 0 };
+
+    // Restoring a large library is slow, and until now it said nothing until
+    // it had finished -- so a node that was working and a node that was stuck
+    // looked identical for as long as it took, which on a real library was
+    // long enough to reach for a debugger. Reported on a timer rather than per
+    // archive, so a small library stays quiet and a large one stops being a
+    // mystery.
+    const startedAt = Date.now();
+    const progress = setInterval(() => {
+      const seconds = Math.round((Date.now() - startedAt) / 1000);
+      console.log(
+        `[restore] ${tally.restored + tally.failed} of ${entries.length} ` +
+          `after ${seconds}s`,
+      );
+    }, 15_000);
+    progress.unref?.();
 
+    try {
+      return await this.#restoreEach(entries, tally);
+    } finally {
+      clearInterval(progress);
+    }
+  }
+
+  /**
+   * The restore loop itself.
+   *
+   * Counts into the caller's tally rather than its own, so the progress timer
+   * above has something to read while this is still running.
+   * @param {object[]} entries - Catalog entries, newest first.
+   * @param {{restored: number, failed: number}} tally - Mutated as it goes.
+   * @returns {Promise<{restored: number, failed: number}>} - That tally.
+   */
+  async #restoreEach(entries, tally) {
     for (const entry of entries) {
       // An engine that cannot open its port will fail every one of these, each
       // after its own timeout. Stopping at the first is the difference between
@@ -1473,13 +1505,13 @@ export class Library {
       // minutes per archive.
       if (this.#engine.fatalError) {
         console.error(`[restore] stopping: ${this.#engine.fatalError.message}`);
-        failed += entries.length - restored;
+        tally.failed += entries.length - tally.restored;
         break;
       }
 
       try {
         if (!entry.torrentPath && !entry.magnet) {
-          failed++;
+          tally.failed++;
           continue;
         }
 
@@ -1495,7 +1527,7 @@ export class Library {
                 `usable (${error.code ?? error.message}), so it cannot start. ` +
                 'Move it with Set location, or make that path reachable again.',
             );
-            failed++;
+            tally.failed++;
             continue;
           }
         }
@@ -1505,14 +1537,14 @@ export class Library {
         // own add and skip that, which is why an archive that could not find a
         // peer stayed unable to find one across every restart.
         await this.#readd(entry);
-        restored++;
+        tally.restored++;
       } catch (error) {
-        failed++;
+        tally.failed++;
         console.error(`[restore] ${entry.name}: ${error.message}`);
       }
     }
 
-    return { restored, failed };
+    return tally;
   }
 
   /**

package/src/publisher.js

@@ -21,6 +21,30 @@
  * so republishing on a timer is not an optimisation here — it is the feature.
  */
 
+/*
+ * Why this uses bittorrent-dht rather than an engine's own DHT.
+ *
+ * Both seeding engines run a DHT already, so a third one looks redundant.
+ * It is not, for two different reasons:
+ *
+ *   libtorrent   - its DHT lives in the Python sidecar, and the 2.x Python
+ *                  bindings do not expose dht_put_item or dht_get_item at all.
+ *                  The alerts are bound (dht_mutable_item_alert, dht_put_alert)
+ *                  so the C++ side supports BEP 44, but there is no method to
+ *                  start one. Checked against 2.0.13; worth re-checking if a
+ *                  later binding adds them, because a sidecar op would then be
+ *                  the tidier answer for a libtorrent-only node.
+ *
+ *   webtorrent   - its DHT *is* bittorrent-dht, reachable as `client.dht`, so
+ *                  reusing it is possible and would save a socket. Not done,
+ *                  to keep one code path that behaves the same whichever
+ *                  engine is configured.
+ *
+ * The dependency itself costs nothing: webtorrent already depends on the same
+ * version, and npm dedupes them to one install. Declaring it directly only
+ * removes the reliance on a transitive.
+ */
+
 import { mutableMagnet, publishInfoHash } from './mutable.js';
 
 /** Republish well inside the ~2h a DHT keeps an item. */