pmtiles-swarm 0.65.0 → 0.67.0

package/CHANGELOG.md

@@ -4,6 +4,62 @@
 ### ✨ Features and improvements
 - _...Add new stuff here..._
 
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.67.0
+### ✨ Features and improvements
+- **An exported archive is dated, and the filename is its own field.** Both the archive's name and
+  the file it lands in now carry the date by default, and both can be changed — separately. They
+  answer different questions: `Terrain-20260822.pmtiles` is what somebody finds on disk,
+  `Terrain 20260822` is what a map client shows, and tying one to the other only guarantees that
+  one of them is wrong whenever they should differ.
+
+  A filename given by hand is reduced to a single path segment before it is used, because it is
+  joined to a save path and a filename is exactly the kind of field somebody puts a slash in.
+  `../../etc/passwd` is tested.
+
+  The description starts empty and stays empty unless something is typed. It used to be
+  prefilled from the recipe, which is a different thing — a recipe describes how tiles are
+  combined, an archive describes what it is, and only the person exporting it knows that. The
+  server no longer falls back to the recipe either: filling in a field the dialog showed as
+  blank is a worse surprise than having no description. The date is recorded there regardless,
+  because a name can be changed to anything and then nothing else says when the archive was
+  made.
+
+  This corrects something 0.64.0 asserted and this project does not do. The name was left undated
+  on the reasoning that `/latest/<category>/` follows a rebuild by name. It does not: it resolves a
+  category and takes the newest by date, and nothing here looks an archive up by name at all — the
+  only name comparison in the codebase refuses two archives the same *file* path. The
+  documentation said so as well, and now says what is true.
+
+
+
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.66.0
+### ✨ Features and improvements
+- **An export asks where it should go, and what to call it.** **Export to archive** now opens a
+  dialog instead of a confirmation, because there is something to decide. The save location uses
+  the same picker every other destination in this console uses, so a location named once under
+  Settings is offered here too — a baked planet is hundreds of gigabytes and which disk it lands on
+  is not a detail. The name and description default to the stack's and can be changed.
+
+  The filename is shown as the name is typed. A name is not a filename — separators and the
+  characters Windows refuses become dashes, and the date is appended so successive builds do not
+  collide — and a preview promising one thing while the server writes another would be worse than
+  no preview at all. A test asserts the browser's rule and `safeSegment` agree.
+
+### 🐞 Bug fixes
+- **A save location the node did not know was silently ignored.** The export resolved it after the
+  merge and swallowed the error, so naming a location that did not exist, or one that could not be
+  written, meant an hour of merging answered with a shrug and the archive on the default disk. It
+  is resolved before anything starts and the error is allowed through, which is what lets the
+  dialog put it beside the field that caused it.
+
+
+
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 

package/docs/tile-stacks.md

@@ -698,14 +698,26 @@ resolves to whichever build is current, so the same recipe over a rebuilt source
 is a different bake — and a checkpoint that could not tell would resume across
 the change and produce an archive that is half one map and half another.
 
-The file is dated: `Terrain-20260822.pmtiles`. The archive's **name** is not.
-A rebuild here keeps its name and mints a new infohash, which is what lets
-`/latest/<category>/` follow it; dating the name would make every build a
-different map. The date goes in `description` instead, so an archive read out of
-context still says what produced it and when.
+Both the file and the archive's name are dated, and both can be changed —
+separately, because they answer different questions. `Terrain-20260822.pmtiles`
+is what somebody finds on disk; `Terrain 20260822` is what a map client shows.
+Tying one to the other only guarantees that one of them is wrong whenever they
+should differ.
+
+An earlier version of this document said the name had to stay undated so
+`/latest/<category>/` could follow a rebuild. That was wrong. `/latest/`
+resolves a category and takes the newest by date; nothing in this project looks
+an archive up by name at all, and the only name comparison there is refuses two
+archives the same _file_ path. A dated name is free, and it answers the question
+somebody holding two builds actually has.
 
 `name` is always written, because these archives get converted to mbtiles by
-other tools and a nameless metadata block is not valid there.
+other tools and a nameless metadata block is not valid there. The date also goes
+in `description`, so an archive read out of context says what produced it.
+
+A chosen filename is reduced to one path segment before it is used. That is not
+politeness — the name is joined to a save path, and a filename is exactly the
+kind of field somebody puts a slash in.
 
 ### What a baked archive says about itself
 
@@ -730,6 +742,21 @@ worth writing at all.
 planet bake is hours, and a request that waited for the archive is a request
 nothing could hold open. `DELETE` on the same address stops it.
 
+The button opens a dialog rather than a confirmation, because there is
+something to decide. **Where it lands** uses the same picker every other
+destination in this console uses, so a location named once under Settings is
+offered here too — and a baked planet is hundreds of gigabytes, so which disk it
+goes on is not a detail. The location is resolved _before_ anything is merged:
+a name this node does not know, or a path it cannot write, is the caller's
+mistake and they can fix it, but only if they are told now rather than an hour
+later.
+
+**What it is called** is two fields, both dated by default and both editable:
+the archive's name, and the filename. The dialog says what a filename will
+actually become where sanitising would change it, using the same rule the server
+applies — a field that shows one filename while the server writes another is
+worse than a field that shows nothing.
+
 A bake has two halves and they are watched in two places, deliberately. Merging
 is about a stack, so it is reported on the stack — tiles written, tiles skipped,
 the zoom it is working through. What happens afterwards is an archive being

package/package.json

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

@@ -3181,6 +3181,8 @@ export function createApp({
           categories: req.body?.categories,
           location: req.body?.location,
           savePath: req.body?.savePath,
+          name: req.body?.name,
+          description: req.body?.description,
         });
         return res.status(202).json({ bake: job });
       } catch (error) {

package/src/bake-jobs.js

@@ -3,6 +3,7 @@ import {
   assertBakeable,
   bakeRevision,
   bakeStack,
+  bakedArchiveName,
   bakedName,
   mergeTileFor,
 } from './bake.js';
@@ -113,9 +114,27 @@ export class BakeManager {
       throw error;
     }
 
+    // Resolved before anything starts, and allowed to throw. A location that
+    // does not exist or cannot be written is the caller's mistake and they can
+    // fix it -- but only if they are told now. Checked at the end instead, it
+    // is an hour of merging answered with a shrug and the default disk.
+    const publishDir =
+      options.publishDir ?? (await this.#savePath(options)) ?? undefined;
+
+    // Both dated by default and both overridable, separately: the archive's
+    // name is what a map client shows, and the filename is what somebody finds
+    // on disk. Tying them together only means one of the two is wrong whenever
+    // they should differ.
+    const when = new Date();
+    const archiveName = bakedArchiveName(resolved, {
+      name: options.name,
+      when,
+    });
+
     const job = {
       stackId,
       title: resolved.stack.title ?? stackId,
+      archiveName,
       phase: 'merging',
       startedAt: new Date().toISOString(),
       written: 0,
@@ -126,7 +145,8 @@ export class BakeManager {
       finishedAt: null,
       error: null,
       infoHash: null,
-      name: bakedName(resolved, { when: new Date() }),
+      name: bakedName(resolved, { filename: options.filename, when }),
+      publishDir,
     };
     this.#jobs.set(stackId, job);
 
@@ -171,6 +191,7 @@ export class BakeManager {
         workDir,
         destination,
         format,
+        options,
       );
     } finally {
       await pixels?.close().catch(() => {});
@@ -185,7 +206,7 @@ export class BakeManager {
       // Moved out of the working directory as it is taken on, so a finished
       // archive does not live among the checkpoint files of the job that made
       // it.
-      publishDir: options.publishDir ?? (await this.#savePath(options)),
+      publishDir: job.publishDir,
       mode: 'mirror',
     });
 
@@ -205,7 +226,16 @@ export class BakeManager {
    * @param {string} format - The output format.
    * @returns {Promise<void>} - Resolves when the file is written.
    */
-  async #merge(job, resolved, codec, pixels, workDir, destination, format) {
+  async #merge(
+    job,
+    resolved,
+    codec,
+    pixels,
+    workDir,
+    destination,
+    format,
+    options,
+  ) {
     // Read through the tile store rather than off the disk, so a cache-mode
     // source is scanned the same way it is served: its directories come out of
     // the swarm, and the store holds them to its own byte budget.
@@ -249,8 +279,11 @@ export class BakeManager {
       header: { format },
       pauseMs: this.#config.stacks?.bakePauseMs ?? 0,
       metadata: {
-        name: resolved.stack.title ?? job.stackId,
-        description: resolved.stack.description,
+        name: job.archiveName,
+        // Only what was asked for. Falling back to the recipe's own
+        // description would fill in a field the dialog showed as empty, which
+        // is a worse surprise than having no description at all.
+        description: options.description,
         attribution: resolved.stack.attribution,
         encoding: resolved.stack.output?.encoding,
         encodingFactors: resolved.stack.output,
@@ -273,9 +306,10 @@ export class BakeManager {
    * @returns {Promise<string|undefined>} - A path, or undefined for the default.
    */
   async #savePath(options) {
-    const explicit = await this.#library
-      .resolveSavePath(options)
-      .catch(() => undefined);
+    // Not caught. `resolveSavePath` refuses a name this node does not know and
+    // a path it cannot write, and both are worth refusing rather than quietly
+    // putting hundreds of gigabytes somewhere else.
+    const explicit = await this.#library.resolveSavePath(options);
     return explicit ?? this.#config.savePath ?? undefined;
   }
 
@@ -295,6 +329,8 @@ export class BakeManager {
       skipped: job.skipped,
       zoom: job.zoom,
       name: job.name,
+      archiveName: job.archiveName,
+      publishDir: job.publishDir ?? null,
       infoHash: job.infoHash,
       error: job.error,
     };

package/src/bake.js

@@ -228,19 +228,45 @@ function stamp(when = new Date()) {
 /**
  * What to call the file a bake writes.
  *
- * Dated, because successive bakes of one stack are successive builds of one
- * map and two files cannot share a path. The archive's *name* is not dated --
- * see `bakedMetadata` -- so a rebuild keeps its identity the way every other
- * rebuild here does.
+ * Dated by default, because successive bakes of one stack are successive builds
+ * of one map and two files cannot share a path.
+ *
+ * A caller may name it instead, and what they ask for is reduced to a single
+ * path segment before it is used. That is not politeness: this name is joined
+ * to a directory, and a filename is exactly the kind of field somebody puts a
+ * slash in.
  * @param {object} resolved - The resolved stack.
- * @param {object} [options] - `when`, and `suffix` to break a tie.
- * @returns {string} - A filename.
+ * @param {object} [options] - `filename` to choose one outright, and `when`.
+ * @returns {string} - A filename, always ending `.pmtiles`.
  */
 export function bakedName(resolved, options = {}) {
+  const requested = String(options.filename ?? '').trim();
+  if (requested) {
+    const stem = safeSegment(requested.replace(/\.pmtiles$/i, ''));
+    if (stem) return `${stem}.pmtiles`;
+  }
+
   const title = resolved.stack.title ?? resolved.stack.id;
   const slug = safeSegment(title) || 'stack';
-  const tail = options.suffix ? `-${options.suffix}` : '';
-  return `${slug}-${stamp(options.when)}${tail}.pmtiles`;
+  return `${slug}-${stamp(options.when)}.pmtiles`;
+}
+
+/**
+ * What to call the archive itself.
+ *
+ * Dated too, and separately from the file. Nothing in this project looks an
+ * archive up by name -- `/latest/<category>/` follows a category and takes the
+ * newest by date -- so a dated name costs nothing and says which build you are
+ * looking at, which is the question somebody holding two of them has.
+ * @param {object} resolved - The resolved stack.
+ * @param {object} [options] - `name` to choose one outright, and `when`.
+ * @returns {string} - The name.
+ */
+export function bakedArchiveName(resolved, options = {}) {
+  const explicit = String(options.name ?? '').trim();
+  if (explicit) return explicit;
+  const title = resolved.stack.title ?? resolved.stack.id;
+  return `${title} ${stamp(options.when)}`;
 }
 
 /**

package/src/web/index.html

@@ -644,6 +644,68 @@
       </form>
     </dialog>
 
+    <dialog id="bake-dialog">
+      <form method="dialog" id="bake-form">
+        <h2>Export to archive</h2>
+        <div class="sub" style="margin-bottom:0.8rem">
+          Runs the recipe over its sources and writes the result as a real
+          archive, with its own infohash, seeded like any other. It reads every
+          tile the sources hold, so it can take hours — and it can be stopped,
+          which keeps the work for the next run to carry on from.
+        </div>
+
+        <div class="field">
+          <label>Stack</label>
+          <div class="sub"><code id="bake-stack"></code></div>
+        </div>
+
+        <div class="field">
+          <label for="bake-name">Name</label>
+          <input id="bake-name" placeholder="Terrain 20260101" />
+          <div class="sub">
+            What the archive calls itself, and what a map client shows. Dated by
+            default, because two builds of one map are easier to tell apart that
+            way — nothing here looks an archive up by name, so it is free to say
+            whatever is useful.
+          </div>
+        </div>
+
+        <div class="field">
+          <label for="bake-file">Filename</label>
+          <input id="bake-file" placeholder="Terrain-20260101.pmtiles" />
+          <div class="sub" id="bake-filename"></div>
+        </div>
+
+        <div class="field">
+          <label for="bake-description">Description</label>
+          <input id="bake-description" placeholder="" />
+          <div class="sub">
+            Optional, and empty by default — what a stack merges is the
+            operator's business and not something to guess at. The date this was
+            baked is recorded here whether or not anything else is.
+          </div>
+        </div>
+
+        <div id="bake-location"></div>
+
+        <div class="field">
+          <label for="bake-categories">Categories</label>
+          <input id="bake-categories" placeholder="terrain, weekly" />
+          <div class="sub">
+            Comma separated. What the archive is filed under once it is added,
+            which is what <code>/latest/&lt;category&gt;/</code> follows. Left
+            empty, it takes the stack's own.
+          </div>
+        </div>
+
+        <div class="sub" id="bake-error" style="color: var(--danger)"></div>
+        <menu>
+          <button value="cancel">Cancel</button>
+          <button id="bake-go" value="default">Export</button>
+        </menu>
+      </form>
+    </dialog>
+
     <dialog id="adopt-dialog">
       <form method="dialog" id="adopt-form">
         <h2>Adopt existing torrents</h2>
@@ -7678,6 +7740,114 @@ Every piece is hashed against the ` +
       $('stacks-add').onclick = () =>
         openStackDialog().catch((e) => toast(e.message));
 
+      /**
+       * Asks where an export should land before starting it.
+       *
+       * A dialog rather than a confirm, because there is something to decide:
+       * a baked planet is hundreds of gigabytes and the disk it goes on is not
+       * a detail. The same picker every other destination in this console
+       * uses, so a location named once under Settings is offered here too.
+       * @param {string} id - The stack to export.
+       * @returns {Promise<void>} - Resolves once it is asked for or dismissed.
+       */
+      async function openBakeDialog(id, stack) {
+        const title = stack?.title ?? id;
+        const day = new Date().toISOString().slice(0, 10).replaceAll('-', '');
+
+        $('bake-stack').textContent = id;
+        $('bake-error').textContent = '';
+        $('bake-name').value = `${title} ${day}`;
+        $('bake-file').value = `${bakeSlug(title)}-${day}.pmtiles`;
+        // Blank rather than the stack's own description. A recipe describes
+        // how tiles are combined; an archive describes what it is, and only
+        // the person exporting it knows that.
+        $('bake-description').value = '';
+        $('bake-categories').value = (stack?.categories ?? []).join(', ');
+        showBakeFilename();
+        $('bake-location').innerHTML = locationPicker('bake-loc');
+        await fillLocations('bake-loc');
+        $('bake-dialog').showModal();
+      }
+
+      /**
+       * A name reduced to something usable as one path segment.
+       *
+       * The same rules `safeSegment` applies on the server, and a test holds
+       * the two together — a field that shows one filename while the server
+       * writes another is worse than a field that shows nothing.
+       * @param {string} typed - What somebody entered.
+       * @returns {string} - A safe segment, never empty.
+       */
+      function bakeSlug(typed) {
+        const slug = typed
+          .replace(/[/\\<>:"|?*\u0000-\u001f\u007f -]/g, '-')
+          .replace(/-{2,}/g, '-')
+          .replace(/^[.\s-]+/, '')
+          .replace(/[.\s-]+$/, '')
+          .slice(0, 120)
+          .replace(/[.\s-]+$/, '');
+        return slug || 'stack';
+      }
+
+      /**
+       * Says what the file will actually be called, where that differs.
+       *
+       * A filename is exactly the kind of field somebody puts a slash in, and
+       * the server reduces it to one path segment before joining it to a
+       * directory. Saying so here means it is not a surprise.
+       * @returns {void}
+       */
+      function showBakeFilename() {
+        const typed = $('bake-file').value.trim();
+        const note = $('bake-filename');
+        if (!typed) {
+          note.textContent = 'Left empty, it is named after the stack and dated.';
+          return;
+        }
+        const settled = `${bakeSlug(typed.replace(/\.pmtiles$/i, ''))}.pmtiles`;
+        note.textContent =
+          settled === typed ? '' : `Saved as ${settled}`;
+      }
+
+      $('bake-file').addEventListener('input', showBakeFilename);
+
+      $('bake-form').addEventListener('submit', async (event) => {
+        if (event.submitter?.value === 'cancel') return;
+        event.preventDefault();
+
+        const id = $('bake-stack').textContent;
+        const categories = $('bake-categories')
+          .value.split(',')
+          .map((one) => one.trim())
+          .filter(Boolean);
+        const name = $('bake-name').value.trim();
+        const filename = $('bake-file').value.trim();
+        const description = $('bake-description').value.trim();
+
+        try {
+          await api(`/api/stacks/${encodeURIComponent(id)}/bake`, {
+            method: 'POST',
+            body: {
+              ...chosenLocation('bake-loc'),
+              ...(categories.length > 0 ? { categories } : {}),
+              ...(name ? { name } : {}),
+              ...(filename ? { filename } : {}),
+              ...(description ? { description } : {}),
+            },
+          });
+        } catch (error) {
+          // Kept open, because the answer is usually something to change here
+          // -- a location that does not exist, or a codec that is not
+          // installed -- rather than something to go away and think about.
+          $('bake-error').textContent = error.message;
+          return;
+        }
+
+        $('bake-dialog').close();
+        toast(`Exporting ${id}`);
+        loadStacks().catch((e) => toast(e.message));
+      });
+
       // Editing and deleting hang off the list, which is redrawn on every
       // change, so they are delegated the same way the source rows are.
       $('stacks-list').addEventListener('click', async (event) => {
@@ -7686,27 +7856,11 @@ Every piece is hashed against the ` +
         const bake = event.target.dataset.stackBake;
         const stopBake = event.target.dataset.stackBakeStop;
         if (bake !== undefined) {
-          // Confirmed, because it is not a small thing: it reads every tile
-          // every source holds, writes a whole archive, and then hashes it.
-          if (
-            !confirm(
-              `Run "${bake}" over its sources and write the result as a new ` +
-                'archive?\n\nThis reads every tile the sources hold and can ' +
-                'take hours. It can be stopped, and stopping keeps the work.',
-            )
-          ) {
-            return;
-          }
-          try {
-            await api(`/api/stacks/${encodeURIComponent(bake)}/bake`, {
-              method: 'POST',
-              body: {},
-            });
-            toast(`Exporting ${bake}`);
-          } catch (error) {
-            toast(error.message);
-          }
-          loadStacks().catch((e) => toast(e.message));
+          const { stacks } = await api('/api/stacks');
+          await openBakeDialog(
+            bake,
+            stacks.find((one) => one.id === bake),
+          ).catch((e) => toast(e.message));
         } else if (stopBake !== undefined) {
           try {
             await api(`/api/stacks/${encodeURIComponent(stopBake)}/bake`, {