pmtiles-swarm 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## master
 ### ✨ Features and improvements
+- **A watched folder can ask for its stable name to be a hard link.**
+  `latestLinkType: "hard"` reverses the order the two kinds are attempted in,
+  for a folder whose archives are read *through* that name rather than followed
+  to see where it points. A hard link still resolves after the build it names
+  is retired; a symlink is left pointing at nothing, which a tile endpoint
+  reports as a missing archive while the bytes are still on the disk. The other
+  kind remains the fallback in both directions, and the log now always says
+  which was made rather than only mentioning the unexpected one.
 - **The default trackers now include WebSocket ones.** They were two `udp://` entries, so an
   archive created with stock configuration was undiscoverable from a browser — healthy in a
   desktop client, invisible from a page, with nothing in either to say why. A browser speaks

package/docs/publishing.md

@@ -377,6 +377,24 @@ A new `.pmtiles` appearing in a watched folder is imported automatically.
 
 Editable in **Settings → Monitored folders** as a table, rather than by hand.
 
+### What kind of link the stable name is
+
+`latestLink` is made as a symlink by default. Set `latestLinkType: "hard"` on
+the folder when something reads the archive *through* that name — a tile
+server, or anything else that opens it rather than following it to see where it
+points.
+
+The difference only shows when the build the name refers to goes away. A hard
+link is another name for the same bytes, so it still resolves; a symlink is
+left pointing at nothing. Retention repoints the name as it retires a build, so
+neither case arises from ordinary housekeeping — but a rebuild that fails
+between the two steps leaves a reader working in one arrangement and broken in
+the other.
+
+The other kind stays the fallback either way: Windows refuses symlinks without
+elevation, and a hard link cannot cross a filesystem, so the name is still made
+whichever was asked for. The log says which it got.
+
 ### One folder, several kinds of build
 
 Categories and retention are decided per entry, not per directory. A generator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.17.1",
+  "version": "0.18.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/config.js

@@ -613,6 +613,15 @@ const DEFAULTS = {
    * ever touch archives this same folder imported, and never remove the
    * newest build however old it gets.
    *
+   * `latestLinkType` picks how `latestLink` is made: `symbolic` (the default),
+   * or `hard` for a name something reads the archive through. A hard link
+   * still resolves after the build it names is retired, where a symlink is
+   * left pointing at nothing — so a tile endpoint opening that name keeps
+   * working across a rebuild either way, and only one of them keeps working if
+   * the rebuild fails halfway. The other kind stays the fallback in both
+   * directions, since Windows refuses symlinks without elevation and a hard
+   * link cannot cross a filesystem.
+   *
    * `match` is a glob tested against the filename, for a folder holding more
    * than one kind of build. Categories are decided per entry, so several
    * entries can watch one folder and each take only its own archives:

package/src/latest-link.js

@@ -20,21 +20,35 @@ import path from 'node:path';
  * this names is eventually deleted: a symlink is left dangling, while a hard
  * link keeps the bytes alive until it too is gone. Retention never removes the
  * newest build, so neither case arises from this node's own housekeeping.
+ *
+ * `type` chooses which is preferred, because which one is better depends on
+ * what opens the name. Something reading the archive through this link — a
+ * tile endpoint, say — is better served by a hard link: if the build it names
+ * is removed before the name is repointed, a hard link still resolves to the
+ * bytes while a symlink resolves to nothing. The other order is the default
+ * only because it is what has always happened here.
  * @param {object} options - What to link and how to say so.
  * @param {string} options.target - The build the name should resolve to.
  * @param {string} options.name - The stable name, absolute or beside the target.
  * @param {string} options.label - How to name the caller in the log.
+ * @param {string} [options.type] - 'symbolic' (default), 'hard', or 'auto'.
  * @returns {Promise<string|undefined>} - The link made, or undefined on failure.
  */
-export async function linkLatest({ target, name, label }) {
+export async function linkLatest({ target, name, label, type = 'symbolic' }) {
   const link = linkPathFor(target, name);
 
-  const attempts = [
+  const symbolic = [
     // The type is autodetected from the target on Windows and ignored
     // everywhere else, which is right: the target is always a file here.
-    ['symlink', () => fs.symlink(target, link)],
-    ['hard link', () => fs.link(target, link)],
+    'symlink',
+    () => fs.symlink(target, link),
   ];
+  const hard = ['hard link', () => fs.link(target, link)];
+
+  // Both orders keep the other as a fallback rather than failing outright:
+  // Windows refuses symlinks without elevation, and a hard link cannot cross a
+  // filesystem. Whichever is asked for, the name still gets made.
+  const attempts = type === 'hard' ? [hard, symbolic] : [symbolic, hard];
 
   for (const [kind, make] of attempts) {
     try {
@@ -42,10 +56,10 @@ export async function linkLatest({ target, name, label }) {
       // per build and the name by definition already exists after the first.
       await fs.rm(link, { force: true });
       await make();
-      console.log(
-        `${label} latest -> ${path.basename(target)}` +
-          (kind === 'symlink' ? '' : ` (${kind})`),
-      );
+      // Always says which kind. Reporting only the unexpected one meant the
+      // common case was silent, and the only way to learn what you had was to
+      // list the directory and read the mode bits.
+      console.log(`${label} latest -> ${path.basename(target)} (${kind})`);
       return link;
     } catch (error) {
       // Try the next kind rather than giving up on the first refusal; only the

package/src/watch.js

@@ -214,6 +214,10 @@ export class WatchManager {
           target: entry.retainedAt ?? path.join(entry.savePath, entry.name),
           name: folder.latestLink,
           label: `[watch] ${folder.path}`,
+          // Per folder: a folder whose archives are opened through this
+          // name wants a hard link, one that is only a convenience for a
+          // person browsing the directory does not care.
+          type: folder.latestLinkType,
         });
       }
 

package/src/web/index.html

@@ -3427,6 +3427,14 @@
               label: 'Stable name',
               placeholder: 'off',
             },
+            {
+              field: 'latestLinkType',
+              label: 'Stable name is a',
+              options: [
+                ['', 'symlink'],
+                ['hard', 'hard link'],
+              ],
+            },
             {
               field: 'keep',
               label: 'Builds to keep',