pmtiles-swarm 0.75.0 → 0.76.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 
+## 0.76.0
+### ✨ Features and improvements
+- **A stopped export stays stopped.** Stopping one left a checkpoint, and a checkpoint says what was
+  in progress but not why it stopped - so the next restart could not tell somebody pressing Stop
+  from a crash, and picked it up again. Stopping now writes a marker beside the checkpoint, and a
+  restart reports what it is holding rather than resuming it. Starting or resuming clears the marker.
+
+  And the work can be thrown away, which it could not be before: `DELETE /api/stacks/:id/bake/work`
+  removes the working directory, which for an abandoned export is hundreds of gigabytes of buffered
+  tiles that previously had to be found by hand. Refused while a merge is running rather than pulled
+  out from under it.
+
+### 🐞 Bug fixes
+- **An edit inside one clock tick went unnoticed.** `stacks.json` is re-read when its modification
+  time changes, and a filesystem's clock is coarser than an edit: on NTFS the tick is about 15 ms,
+  measured here at 36 rapid rewrites in 40 landing on the same timestamp. Two edits that close
+  together left the mtime alone and the second was never read.
+
+  The size is compared as well now, which catches the ones that changed the file's length - most of
+  them - and costs nothing, since the stat was already being made.
+
+  This is also what made the reload test flake, roughly one run in three: it wrote the file twice in
+  quick succession and then depended on how those two writes fell against the clock. It stamps both
+  writes to the same instant now and asserts they really are the same, so it tests whether a change
+  is noticed rather than whether the clock happened to tick.
+- **A stack with a shallow global source served holes above z14.** How far the merge would climb
+  for a source with no tile at this zoom was a fixed six levels. GEBCO is z0-8 and the sea floor has
+  no more detail to give, so a stack serving z16 has to upscale that z8 tile eight levels - and at
+  z15 the climb stopped one short of the only tile that existed. Over open water, where the other
+  source was sparse and had nothing either, no source contributed at all and the stack correctly
+  answered no-tile. A rectangular hole, one tile wide, in the middle of the sea.
+
+  It is derived now rather than fixed: the deepest zoom the stack serves, less the shallowest source
+  under it. Nothing to set and nothing to get wrong - the right answer is computable, and a smaller
+  one would only punch holes. Somebody who wants the merge to stop climbing says so with `maxzoom`,
+  which stops the stack serving that deep at all: the same wish, said where it also stops the work.
+  Never below the old six, so no stack reaches less far than it did.
+
 ## 0.75.0
 ### ✨ Features and improvements
 - **`maskRange`, because nodata is a band and not a number.** `maskValues` and `maskColors` both

package/package.json

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

package/src/api.js

@@ -3303,6 +3303,31 @@ export function createApp({
     }),
   );
 
+  /**
+   * Throws away what a stopped export had done.
+   *
+   * Separate from stopping, and deliberately a second decision. Stopping keeps
+   * the work because an export may be hours in and somebody may want it back;
+   * this is for when they do not, and until now the only way to be rid of
+   * hundreds of gigabytes of buffered tiles was to find the directory by hand.
+   */
+  app.delete(
+    '/api/stacks/:id/bake/work',
+    route(async (req, res) => {
+      if (!bakes) {
+        return res.status(501).json({ error: 'this node does not bake' });
+      }
+      const discarded = await bakes.discard(req.params.id);
+      if (!discarded) {
+        return res.status(409).json({
+          error:
+            'there is no stopped export for that stack, or one is still running',
+        });
+      }
+      return res.json({ discarded: true });
+    }),
+  );
+
   /**
    * Creates or replaces a stack.
    *

package/src/bake-jobs.js

@@ -7,7 +7,11 @@ import {
   bakeStack,
   bakedArchiveName,
   bakedName,
+  clearStopped,
+  discardCheckpoint,
+  markStopped,
   mergeTileFor,
+  wasStopped,
 } from './bake.js';
 import { PixelWorker } from './pixels.js';
 import { outputFormat } from './stack-tile.js';
@@ -124,6 +128,10 @@ export class BakeManager {
   #loadCodec;
   #cutlines;
   #jobs = new Map();
+  // Exports somebody stopped, whose work is still on disk. Kept so the console
+  // can offer to resume or discard them: after a restart there is no job in
+  // memory, only a directory nobody would think to look for.
+  #held = new Map();
 
   /**
    * @param {object} deps - The library, the tile store, the config and the codec probe.
@@ -152,11 +160,36 @@ export class BakeManager {
    */
   get(stackId) {
     const job = this.#jobs.get(stackId);
-    return job ? this.#describe(job) : null;
+    if (job) return this.#describe(job);
+
+    // Nothing running, but work somebody stopped may still be there. Reported
+    // in the same shape so the console has one thing to read.
+    const stopped = this.#held.get(stackId);
+    if (!stopped) return null;
+    return {
+      stackId,
+      phase: 'stopped',
+      written: stopped.written,
+      resumable: true,
+      ...stopped.describe,
+    };
+  }
+
+  /**
+   * Every stack with work waiting that nobody has decided about.
+   * @returns {string[]} - Their ids.
+   */
+  heldStacks() {
+    return [...this.#held.keys()];
   }
 
   /**
-   * Stops a bake, leaving its work where the next run can pick it up.
+   * Stops a bake, leaving its work for somebody to pick up or throw away.
+   *
+   * Marked as stopped on purpose, so the next start leaves it alone. The work
+   * is still there and `resume` takes it up again -- what changes is who
+   * decides, which for a job that may be hours from finishing should be a
+   * person rather than a restart.
    * @param {string} stackId - Which stack.
    * @returns {boolean} - True if there was one to stop.
    */
@@ -164,10 +197,46 @@ export class BakeManager {
     const job = this.#jobs.get(stackId);
     if (!job || job.finishedAt) return false;
     job.cancelling = true;
+    job.stoppedOnPurpose = true;
     job.controller.abort();
+    // Not awaited: the abort has to reach the merge now, and a mark written a
+    // moment later is still written long before anything restarts.
+    markStopped(workDirFor(job, this.#config)).catch(() => {});
     return true;
   }
 
+  /**
+   * Throws away what a stopped export had done.
+   *
+   * The counterpart to stopping. An export that will not be finished leaves
+   * hundreds of gigabytes of buffered tiles behind, and until now the only way
+   * to be rid of them was to find the directory by hand.
+   * @param {string} stackId - Which stack.
+   * @returns {Promise<boolean>} - True if there was work to discard.
+   */
+  async discard(stackId) {
+    const running = this.#jobs.get(stackId);
+    // Refused rather than raced. Removing the directory under a running merge
+    // would have it fail on its next write, reporting a disk problem for
+    // something somebody chose.
+    if (running && !running.finishedAt) return false;
+
+    let found = false;
+    for (const root of this.#workRoots()) {
+      const directory = path.join(root, WORK_DIR, stackId);
+      const there = await fs
+        .access(directory)
+        .then(() => true)
+        .catch(() => false);
+      if (!there) continue;
+      await discardCheckpoint(directory);
+      found = true;
+    }
+    this.#jobs.delete(stackId);
+    this.#held.delete(stackId);
+    return found;
+  }
+
   /**
    * Picks up exports a previous run did not finish.
    *
@@ -203,6 +272,21 @@ export class BakeManager {
         const resolved = resolve(stackId);
         if (!resolved || bakeRevision(resolved) !== state.revision) continue;
 
+        // Somebody stopped this one. It stays where it is until they say
+        // otherwise -- an export begun again by a restart is the opposite of
+        // what pressing Stop meant.
+        if (await wasStopped(path.join(directory, stackId))) {
+          this.#held.set(stackId, {
+            written: state.written ?? 0,
+            describe: state.describe,
+          });
+          console.log(
+            `[bake] ${stackId} was stopped on purpose; leaving its ` +
+              `${state.written ?? 0} tiles for you to resume or discard`,
+          );
+          continue;
+        }
+
         try {
           const job = await this.start({ resolved, ...state.describe });
           started.push(job);
@@ -367,6 +451,12 @@ export class BakeManager {
     const destination = path.join(workDir, job.name);
     const format = outputFormat(resolved);
 
+    // Running again is the answer to having been stopped, so the mark goes.
+    // Left behind, an export somebody restarted by hand would be passed over
+    // by the next restart, which is the same surprise the other way round.
+    await clearStopped(workDir);
+    this.#held.delete(job.stackId);
+
     // Sized with the batch, so every merge in flight has a thread to do its
     // arithmetic on rather than queueing behind one. Only where there is pixel
     // work to move: a passthrough bake hands bytes straight through and would

package/src/bake.js

@@ -42,6 +42,7 @@ const DEFAULT_CONCURRENCY = 4;
 /** What the working directory holds while a bake is in progress. */
 const FILES = Object.freeze({
   state: 'bake-state.json',
+  stopped: 'bake-stopped.json',
   entries: 'bake-entries.bin',
   tiles: 'bake-tiles.bin',
 });
@@ -59,6 +60,64 @@ export function checkpointPaths(workDir) {
   };
 }
 
+/**
+ * Records that an export was stopped on purpose.
+ *
+ * A checkpoint says what was in progress, not why it stopped, so a crash and
+ * somebody pressing Stop look identical on disk -- and the node picks both up
+ * on the next start. That is right for the crash and wrong for the person, who
+ * stopped it and then watched it begin again.
+ *
+ * Written beside the checkpoint rather than into it, so it cannot be lost to a
+ * half-finished write of the state the export is still making.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<void>} - Resolves once it is written.
+ */
+export async function markStopped(workDir) {
+  await fs
+    .writeFile(
+      path.join(workDir, FILES.stopped),
+      JSON.stringify({ at: new Date().toISOString() }),
+    )
+    .catch(() => {});
+}
+
+/**
+ * Forgets that an export was stopped, because it is running again.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<void>} - Resolves once it is gone.
+ */
+export async function clearStopped(workDir) {
+  await fs
+    .rm(path.join(workDir, FILES.stopped), { force: true })
+    .catch(() => {});
+}
+
+/**
+ * Whether an export was stopped on purpose rather than interrupted.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<boolean>} - True when somebody stopped it.
+ */
+export async function wasStopped(workDir) {
+  return fs
+    .access(path.join(workDir, FILES.stopped))
+    .then(() => true)
+    .catch(() => false);
+}
+
+/**
+ * Forgets an export's unfinished work.
+ *
+ * The whole directory, because a checkpoint is only meaningful with the tiles
+ * it names -- leaving either behind is leaving something that will be picked
+ * up and found wanting.
+ * @param {string} workDir - The bake's working directory.
+ * @returns {Promise<void>} - Resolves once it is gone.
+ */
+export async function discardCheckpoint(workDir) {
+  await fs.rm(workDir, { recursive: true, force: true });
+}
+
 /**
  * One entry, as a checkpoint stores it.
  *

package/src/stack-tile.js

@@ -36,9 +36,42 @@ import { TileReadError } from './tiles.js';
  * a tile in an archive or a hole where one is not needed.
  */
 
-/** How far up the pyramid a merge will climb for a source with no tile here. */
+/**
+ * How far up the pyramid a merge will climb for a source with no tile here,
+ * where the stack does not say and nothing can be worked out.
+ */
 const PARENT_LIMIT = 6;
 
+/**
+ * How far this stack has to climb for its shallowest source to keep working.
+ *
+ * A global source is shallow on purpose -- GEBCO is z0-8 and the sea floor has
+ * no more detail to give -- so serving a stack to z16 means upscaling that z8
+ * tile eight levels. A fixed limit truncates exactly the arrangement this
+ * feature is for: at z15 the climb stopped one level short of the only tile
+ * that exists, no source contributed, and the stack answered no-tile over open
+ * water.
+ *
+ * So it is derived from what the stack spans rather than assumed or set: the
+ * right answer is computable, and a recipe naming a smaller one would only
+ * punch holes in itself. Somebody who wants the merge to stop climbing says so
+ * with `maxzoom`, which stops the stack serving that deep at all -- the same
+ * wish, said where it also stops the work.
+ *
+ * Never below the old fixed limit, so no stack reaches less far than it did.
+ * @param {object} resolved - The resolved stack.
+ * @returns {number} - Levels a source may climb.
+ */
+export function parentLimitFor(resolved) {
+  const { maxzoom } = stackCoverage(resolved);
+  const shallowest = resolved.sources
+    .map((source) => source.entry?.pmtiles?.maxZoom)
+    .filter((zoom) => Number.isFinite(zoom));
+  if (!shallowest.length || !Number.isFinite(maxzoom)) return PARENT_LIMIT;
+
+  return Math.max(PARENT_LIMIT, maxzoom - Math.min(...shallowest));
+}
+
 /** The deepest zoom a tile id is defined for. */
 const MAX_ZOOM = 26;
 
@@ -141,8 +174,8 @@ export function clipsFor(resolved, cutlines, z, x, y, size = 256) {
  * @param {object} options - Source, coordinates, the tile store and whether to climb.
  * @returns {Promise<object|null>} - The tile and the zoom it came from.
  */
-async function readFrom({ source, z, x, y, tiles, climb, signal }) {
-  const floor = climb ? Math.max(0, z - PARENT_LIMIT) : z;
+async function readFrom({ source, z, x, y, tiles, climb, signal, limit }) {
+  const floor = climb ? Math.max(0, z - (limit ?? PARENT_LIMIT)) : z;
   for (let at = z; at >= floor; at -= 1) {
     const shift = z - at;
     const tile = await tiles.getTile(
@@ -322,6 +355,7 @@ export function passThroughRead({
  * @returns {Promise<object>} - `{contributors, contributions}` or `{error}`.
  */
 async function readAll({ resolved, z, x, y, tiles, signal, clips }) {
+  const limit = parentLimitFor(resolved);
   return Promise.all(
     resolved.sources.map(async (source, index) => {
       if (!source.entry) return { source, found: null };
@@ -340,6 +374,7 @@ async function readAll({ resolved, z, x, y, tiles, signal, clips }) {
             tiles,
             climb: true,
             signal,
+            limit,
           }),
         };
       } catch (error) {

package/src/stacks.js

@@ -528,6 +528,7 @@ export class StackStore {
   #stacks = new Map();
   #problems = new Map();
   #mtime = null;
+  #size = null;
   #checkedAt = 0;
 
   /**
@@ -552,10 +553,13 @@ export class StackStore {
     let raw;
     try {
       raw = JSON.parse(await fs.readFile(this.#file, 'utf8'));
-      this.#mtime = (await fs.stat(this.#file)).mtimeMs;
+      const stat = await fs.stat(this.#file);
+      this.#mtime = stat.mtimeMs;
+      this.#size = stat.size;
     } catch (error) {
       if (error.code === 'ENOENT') {
         this.#mtime = null;
+        this.#size = null;
         return;
       }
       throw error;
@@ -588,9 +592,15 @@ export class StackStore {
     if (now - this.#checkedAt < 1000) return false;
     this.#checkedAt = now;
 
+    // Size as well as the timestamp. A filesystem's clock is coarser than an
+    // edit: on NTFS the tick is about 15 ms, so two writes in quick succession
+    // land on the same mtime and the second would never be seen. Comparing the
+    // length as well catches the ones that changed it, which is most of them --
+    // and it costs nothing, since the stat was made anyway.
     const stat = await fs.stat(this.#file).catch(() => null);
     const mtime = stat?.mtimeMs ?? null;
-    if (mtime === this.#mtime) return false;
+    const size = stat?.size ?? null;
+    if (mtime === this.#mtime && size === this.#size) return false;
     await this.load();
     return true;
   }
@@ -676,6 +686,8 @@ export class StackStore {
 `,
     );
     await fs.rename(temp, this.#file);
-    this.#mtime = (await fs.stat(this.#file)).mtimeMs;
+    const written = await fs.stat(this.#file);
+    this.#mtime = written.mtimeMs;
+    this.#size = written.size;
   }
 }

package/src/web/index.html

@@ -1905,18 +1905,21 @@
         );
 
       /**
-       * A mask range as the field shows it.
+       * One end of a mask range, for the box that shows it.
        *
-       * One pair is written plainly; a recipe carrying several is shown as
-       * JSON, because the editor offers one band and the file may hold more
-       * than the editor can draw.
+       * A recipe may hold several bands where the editor offers one. The first
+       * is what the boxes show, and the row says how many more there are --
+       * silently dropping them would be worse than saying the editor cannot
+       * draw them.
        * @param {*} range - What the recipe says.
+       * @param {number} which - 0 for the low end, 1 for the high.
        * @returns {string} - What to put in the box.
        */
-      const rangeText = (range) => {
+      const rangeEdge = (range, which) => {
         if (!Array.isArray(range) || range.length === 0) return '';
-        if (Array.isArray(range[0])) return JSON.stringify(range);
-        return range.slice(0, 2).join(', ');
+        const first = Array.isArray(range[0]) ? range[0] : range;
+        const edge = first[which];
+        return Number.isFinite(Number(edge)) ? String(edge) : '';
       };
 
       /**
@@ -7635,11 +7638,23 @@ Every piece is hashed against the ` +
                       value="${escapeHtml((source.maskValues ?? []).join(', '))}" />
              </label>
              <label class="choice"
-                    title="Mask every height inside a band, written low, high. Nodata is rarely one number: an archive resampled on its way to being built does not hold what it was authored with, so a sea authored as 0 arrives scattered across -0.9 m to 0 — and masking the two ends of that leaves everything between, standing proud of whatever is underneath. A band says what you mean, and asymmetrically: sea is everything up to zero and nothing above it.">
-               Mask range
-               <input style="width:9rem" placeholder="-1, 0"
-                      data-stack-field="maskRange" data-stack-index="${index}"
-                      value="${escapeHtml(rangeText(source.maskRange))}" /> m
+                    title="Mask every height between these two, inclusive. Separate from Mask heights, which takes values one at a time — nodata is often a band rather than a number, because an archive resampled on its way to being built does not hold what it was authored with. A sea authored as 0 arrives scattered across -0.9 m to 0, and masking the two ends of that leaves everything between, standing proud of whatever is underneath. Leave both empty for no band.">
+               Mask between
+               <input type="number" step="any" style="width:5.5rem" placeholder="low"
+                      data-stack-field="maskRangeLow" data-stack-index="${index}"
+                      value="${rangeEdge(source.maskRange, 0)}" />
+               and
+               <input type="number" step="any" style="width:5.5rem" placeholder="high"
+                      data-stack-field="maskRangeHigh" data-stack-index="${index}"
+                      value="${rangeEdge(source.maskRange, 1)}" /> m
+               ${
+                 Array.isArray(source.maskRange) &&
+                 Array.isArray(source.maskRange[0]) &&
+                 source.maskRange.length > 1
+                   ? `<span class="sub">and ${source.maskRange.length - 1} more,
+                      which editing here replaces</span>`
+                   : ''
+               }
              </label>`;
 
         return `
@@ -7761,16 +7776,22 @@ Every piece is hashed against the ` +
             .filter(Boolean);
         } else if (field === 'required') {
           source.required = event.target.checked;
-        } else if (field === 'maskRange') {
-          // Held while it is half-typed, the way the clip box is: four numbers
-          // arrive one keystroke at a time and a field that cleared itself
-          // after the first comma could never be filled in.
-          const numbers = event.target.value
-            .split(',')
-            .map((part) => Number(part.trim()))
-            .filter((n) => Number.isFinite(n));
-          if (numbers.length >= 2) source.maskRange = numbers.slice(0, 2);
-          else if (event.target.value.trim() === '') delete source.maskRange;
+        } else if (field === 'maskRangeLow' || field === 'maskRangeHigh') {
+          // A band needs both ends, so one on its own is a half-typed thought
+          // rather than a range -- read them together, and write nothing until
+          // there are two numbers to write.
+          const row = event.target.closest('.card');
+          const edge = (name) => {
+            const box = row?.querySelector(`[data-stack-field="${name}"]`);
+            return box && box.value.trim() !== '' ? Number(box.value) : null;
+          };
+          const low = edge('maskRangeLow');
+          const high = edge('maskRangeHigh');
+          if (Number.isFinite(low) && Number.isFinite(high)) {
+            source.maskRange = low <= high ? [low, high] : [high, low];
+          } else if (low === null && high === null) {
+            delete source.maskRange;
+          }
         } else if (field === 'feather') {
           const pixels = Number(event.target.value);
           if (event.target.value === '' || !(pixels > 0)) delete source.feather;