pmtiles-swarm 0.41.0 → 0.41.1

package/CHANGELOG.md

@@ -7,6 +7,27 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.41.1
+### ✨ Features and improvements
+
+### 🐞 Bug fixes
+- **`KillMode=mixed` in the documented unit, and it should have been there from the start.** systemd's
+  default is `control-group`, which sends `SIGTERM` to every process in the unit at the same instant —
+  the node and the Python sidecar together. The node's shutdown then asks a sidecar that is already
+  dying to write its resume data, into a pipe that is closing, and the answer never comes.
+
+  Resume data is how an archive comes back knowing what it holds. Without it, archives return at 0%
+  after a restart and only a recheck discovers they were complete all along. `mixed` signals the main
+  process only; the node stops the sidecar itself and waits for the write. Nothing is left running —
+  anything still alive at `TimeoutStopSec` is killed, sidecar included. **Existing installs need this
+  added by hand**, followed by `systemctl daemon-reload`.
+- **The check added in 0.40.0 asked its first question only of archives recorded as complete**, and so
+  missed the case that prompted it. An archive interrupted mid-download comes back recorded as
+  incomplete, so a restore that failed to hand it over left it absent from the engine and unreported
+  by the very check meant to notice — which is what a row reading 0% with no state at all is. Whether
+  the engine is holding an archive is now asked of everything restore handed over; whether the
+  `seedOnly` claim held is still asked only of the archives that make one.
+
 ## 0.41.0
 ### ✨ Features and improvements
 - **An archive's details now open directly under the row you clicked**, instead of below the whole

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

@@ -180,6 +180,11 @@ RestartSec=5
 # lock and cancels downloads in flight. Worst case is about 20 seconds.
 TimeoutStopSec=45
 
+# The node stops the sidecar itself, and needs it alive to do so. The default
+# signals both at once, which kills the sidecar before it can write its resume
+# data — see "The two lines that matter".
+KillMode=mixed
+
 # A seeding node holds a socket per peer, and the tile reader holds file
 # descriptors of its own.
 LimitNOFILE=65535
@@ -215,12 +220,23 @@ down and **exits 0**, expecting to be brought back.
 `Restart=on-failure` ignores an exit 0, so the first use of that button would
 stop the node and leave the unit reporting success.
 
+**`KillMode=mixed`, not the default.** The default is `control-group`, which
+sends `SIGTERM` to _every_ process in the unit at the same instant — the node
+and the Python sidecar together. The node's shutdown then asks a sidecar that is
+already dying to write its resume data, into a pipe that is closing, and the
+answer never comes. Resume data is how an archive comes back knowing what it
+holds; without it, archives return at 0% after a restart and have to be
+rechecked to find out they were complete all along.
+
+`mixed` sends the signal to the main process only. The node stops the sidecar
+itself, in order, and waits for the resume data to be written. Nothing is left
+running: anything still alive when `TimeoutStopSec` expires is killed, sidecar
+included.
+
 **No `ExecStop=`.** systemd already sends `SIGTERM`, and the node handles it
 from the moment it starts. `ExecStop=/bin/kill -15 $MAINPID` is redundant, and
-becomes wrong if the unit ever uses `KillMode=process` — it would stop the node
-while the Python sidecar kept running and kept the data directory locked.
-
-Leave `KillMode` at its default, so the sidecar goes with its parent.
+becomes wrong under `KillMode=process` — that one leaves the rest of the unit
+running indefinitely, so the sidecar would keep the data directory locked.
 
 ## Where it writes
 
@@ -587,8 +603,10 @@ and lives as long as it does, so a new sidecar sits on disk doing nothing until
 the service is restarted. Most of what changes between releases is in there.
 
 Nothing under `/etc/pmtiles-swarm` is touched, and restarting does not re-check
-the archives: a clean stop writes resume data, and `TimeoutStopSec` above
-leaves room for it.
+the archives: a clean stop writes resume data, and `TimeoutStopSec` above leaves
+room for it. That depends on `KillMode=mixed` — without it the sidecar is
+signalled at the same moment as the node and dies before it can write anything,
+which is what a library that comes back at 0% after every restart looks like.
 
 Confirm both halves moved, since the sidecar has its own version:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.41.0",
+  "version": "0.41.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/library.js

@@ -1840,10 +1840,7 @@ export class Library {
    * @returns {Promise<void>} - Resolves once every claim has been checked.
    */
   async #verifySeeding(entries) {
-    const claimed = entries.filter(
-      (entry) => entry.complete !== false && entry.mode !== 'cache',
-    );
-    if (claimed.length === 0) return;
+    if (entries.length === 0) return;
 
     // One listing rather than a status call each: this runs over the whole
     // library on every start, and a round trip per archive is a cost paid by
@@ -1854,25 +1851,37 @@ export class Library {
     }
 
     let wrong = 0;
-    for (const entry of claimed) {
+    for (const entry of entries) {
       const status = held.get(entry.infoHash);
-
-      // Checking is the engine doing the right thing already, and progress
-      // during it is the fraction hashed rather than the fraction held.
-      if (status && (status.progress >= 1 || status.state === 'checking')) {
-        continue;
-      }
-      wrong += 1;
       const label = `[seeding] ${entry.name}`;
 
+      // Held at all is a different question from held whole, and it is asked
+      // of everything restore handed over. Asking it only of complete archives
+      // was the first version of this check, and it missed the case that
+      // prompted it: an archive interrupted mid-download comes back recorded
+      // as incomplete, so a restore that silently failed to hand it over left
+      // it absent from the engine and unreported by the very check meant to
+      // notice. Absent is absent — it is neither seeding nor downloading.
       if (!status) {
+        wrong += 1;
         console.error(
-          `${label}: recorded as complete, but the engine is not holding it ` +
-            'at all — restore counted it and nothing is seeding it.',
+          `${label}: restore handed this to the engine and the engine is not ` +
+            'holding it. It is neither seeding nor downloading, and nothing ' +
+            'will start it before the next restart.',
         );
         continue;
       }
 
+      // Everything below is about the `seedOnly` claim, and only a complete
+      // archive makes one. An incomplete one is supposed to read as a partial
+      // download, so its progress says nothing about whether anything is wrong.
+      if (entry.complete === false || entry.mode === 'cache') continue;
+
+      // Checking is the engine doing the right thing already, and progress
+      // during it is the fraction hashed rather than the fraction held.
+      if (status.progress >= 1 || status.state === 'checking') continue;
+      wrong += 1;
+
       const file = entry.savePath
         ? path.join(entry.savePath, entry.name)
         : null;
@@ -1921,8 +1930,8 @@ export class Library {
 
     if (wrong > 0) {
       console.error(
-        `[seeding] ${wrong} of ${claimed.length} archives recorded as ` +
-          'complete are not being seeded. The lines above say which and why.',
+        `[seeding] ${wrong} of ${entries.length} restored archives are not ` +
+          'in the state the catalog describes. The lines above say which and why.',
       );
     }
   }