feat: shorten paths that exceed the device's limit

Rockbox's MAX_PATH is 260, defined in firmware/include/fs_defines.h and used to
size the directory entry buffer in dir.h. It bounds the path as the device sees
it, so the directory the mirror is copied into spends part of the same budget;
--device-prefix accounts for that and defaults to /Music.

Over-budget paths are shortened from the deepest component outward. The track
name carries the least navigational value and the artist directory the most, so
the filename is cut first and the artist only if nothing else will serve. A
shortened component keeps its extension and gains four hex digits of the
original name: two long titles sharing a prefix cut to the same string
otherwise, and a silent collision between two tracks is a worse outcome than an
ugly filename.

The result is stable. The same source always yields the same shortened name, so
one pass does not rename what the last one wrote -- an unstable scheme would
churn the whole mirror every six hours. A path too deeply nested to fit without
reducing every component to nonsense is left alone and reported rather than
mangled.

Migration now tries more than one previous naming, because there is more than
one. A mirror already running with --fat32-safe holds sanitised but unshortened
paths, and matching only the original unsanitised name would have re-encoded
every one of them instead of moving it.

The checker gains the same two options, since it was measuring the
mirror-relative path against a limit that applies to the device-absolute one,
and so under-reported by the length of the destination directory.

music_mirror.py

@@ -17,6 +17,7 @@ import argparse
 import concurrent.futures
 import fcntl
 import functools
+import hashlib
 import logging
 import os
 import re
@@ -88,6 +89,17 @@ MTIME_TOLERANCE_SECONDS = 2
 # never arrives -- "Kick Out the Epic Motherf**ker" is a real example.
 FAT32_RESERVED = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
 
+# Rockbox's MAX_PATH, from firmware/include/fs_defines.h. It bounds the whole
+# path as the device sees it, so the budget for a mirror-relative path is this
+# less whatever directory the mirror is copied into.
+MAX_PATH = 260
+DEVICE_PREFIX = "/Music"
+
+# A component cut below this is no longer recognisable, and a path that cannot
+# be brought under the limit without going there is better reported than
+# mangled.
+MIN_COMPONENT = 12
+
 # The mirror exists to be read back by something else -- an SMB share, another
 # account on the box -- so everything written into it has to be group-readable.
 # Neither writer manages that unaided: tempfile.mkstemp forces 0600 whatever the
@@ -155,11 +167,56 @@ def fat32_safe(component):
     return cleaned or "_"
 
 
-def mirror_path_for(source, source_root, mirror_root, safe=False):
+def shorten_component(component, budget):
+    """Return a component of at most `budget` characters, marked as shortened.
+
+    The mark is four hex digits of the original name. Two different long names
+    would otherwise cut down to the same string, and a silent collision between
+    two tracks is worse than an ugly filename.
+    """
+    stem, dot, extension = component.rpartition(".")
+    if not dot or len(extension) > 4:
+        stem, extension = component, ""
+    else:
+        extension = dot + extension
+    digest = hashlib.blake2s(component.encode("utf-8"), digest_size=2).hexdigest()
+    tail = f"~{digest}{extension}"
+    return stem[: max(1, budget - len(tail))].rstrip(". ") + tail
+
+
+def fit_path(relative, budget):
+    """Return a relative path within `budget` characters, or the best available.
+
+    Shortened from the deepest component outward. The filename carries the least
+    navigational value and the artist directory the most, so the track name is
+    sacrificed before the album and the album before the artist.
+    """
+    parts = list(relative.parts)
+    for index in reversed(range(len(parts))):
+        overage = len(str(Path(*parts))) - budget
+        if overage <= 0:
+            break
+        allowed = max(MIN_COMPONENT, len(parts[index]) - overage)
+        if allowed < len(parts[index]):
+            parts[index] = shorten_component(parts[index], allowed)
+    fitted = Path(*parts)
+    if len(str(fitted)) > budget:
+        logger.warning(
+            "%s is still %d characters over the limit after shortening; it is too"
+            " deeply nested to fit",
+            relative,
+            len(str(fitted)) - budget,
+        )
+    return fitted
+
+
+def mirror_path_for(source, source_root, mirror_root, safe=False, budget=0):
     """Return the mirror path corresponding to a source file."""
     relative = source.relative_to(source_root).with_suffix(MIRROR_SUFFIX)
     if safe:
         relative = Path(*(fat32_safe(part) for part in relative.parts))
+        if budget > 0 and len(str(relative)) > budget:
+            relative = fit_path(relative, budget)
     return mirror_root / relative
 
 
@@ -357,23 +414,29 @@ def copy(source, mirror, dry_run):
     return Result("copied", mirror)
 
 
-def adopt_existing(source, mirror, previous, dry_run=False):
+def adopt_existing(source, mirror, candidates, dry_run=False):
     """Move an already-encoded file to its new name. Returns whether it moved.
 
     Turning on FAT32-safe naming changes the path of every track whose name
     held a reserved character. Without this the run would encode them all again
     and then prune the originals -- hours of work to produce files that already
     exist, byte for byte, under the old name.
+
+    Several candidates are tried because there is more than one previous
+    naming: the original, and the sanitised-but-not-yet-shortened form left by
+    an earlier version.
     """
-    if previous == mirror or not previous.is_file() or not is_current(source, previous):
-        return False
-    if dry_run:
-        logger.info("would rename %s -> %s", previous.name, mirror.name)
+    for previous in candidates:
+        if previous == mirror or not previous.is_file() or not is_current(source, previous):
+            continue
+        if dry_run:
+            logger.info("would rename %s -> %s", previous.name, mirror.name)
+            return True
+        mirror.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(previous, mirror)
+        logger.info("renamed %s -> %s", previous.name, mirror.name)
         return True
-    mirror.parent.mkdir(parents=True, exist_ok=True)
-    os.replace(previous, mirror)
-    logger.info("renamed %s -> %s", previous.name, mirror.name)
-    return True
+    return False
 
 
 def process(source, mirror, quality_args, dry_run, previous=None):
@@ -407,7 +470,7 @@ def find_sources(root):
             yield path
 
 
-def plan(scan_root, source_root, mirror_root, safe=False):
+def plan(scan_root, source_root, mirror_root, safe=False, budget=0):
     """Map each mirror path to the one source that should produce it.
 
     Two sources can want the same mirror path -- `01 Song.flac` alongside a
@@ -423,7 +486,7 @@ def plan(scan_root, source_root, mirror_root, safe=False):
     # that now beats discovering it as a silent overwrite during the copy.
     seen = {}
     for source in find_sources(scan_root):
-        mirror = mirror_path_for(source, source_root, mirror_root, safe)
+        mirror = mirror_path_for(source, source_root, mirror_root, safe, budget)
         key = str(mirror).casefold() if safe else str(mirror)
         rival_path = seen.get(key)
         rival = chosen.get(rival_path) if rival_path else None
@@ -481,7 +544,15 @@ def prune(mirror_root, expected, dry_run):
 
 
 def run_once(
-    scan_root, source_root, mirror_root, quality_args, jobs, dry_run, do_prune, safe=False
+    scan_root,
+    source_root,
+    mirror_root,
+    quality_args,
+    jobs,
+    dry_run,
+    do_prune,
+    safe=False,
+    budget=0,
 ):
     """Run a single pass. Returns the number of failures.
 
@@ -493,7 +564,7 @@ def run_once(
     counts = {"encoded": 0, "copied": 0, "renamed": 0, "skipped": 0, "failed": 0}
     failures = []
 
-    work = plan(scan_root, source_root, mirror_root, safe)
+    work = plan(scan_root, source_root, mirror_root, safe, budget)
 
     with concurrent.futures.ThreadPoolExecutor(max_workers=jobs) as pool:
         futures = [
@@ -503,7 +574,14 @@ def run_once(
                 mirror,
                 quality_args,
                 dry_run,
-                mirror_path_for(source, source_root, mirror_root) if safe else None,
+                (
+                    [
+                        mirror_path_for(source, source_root, mirror_root),
+                        mirror_path_for(source, source_root, mirror_root, True),
+                    ]
+                    if safe
+                    else None
+                ),
             )
             for mirror, source in work.items()
         ]
@@ -519,9 +597,9 @@ def run_once(
         # on disk. They are not orphans -- they are the files a real run would
         # move -- and reporting them for deletion would misrepresent the pass
         # twice over.
-        expected |= {
-            mirror_path_for(source, source_root, mirror_root) for source in work.values()
-        }
+        for source in work.values():
+            expected.add(mirror_path_for(source, source_root, mirror_root))
+            expected.add(mirror_path_for(source, source_root, mirror_root, True))
     removed = prune(mirror_root, expected, dry_run) if do_prune else 0
 
     for failure in failures:
@@ -617,6 +695,19 @@ def build_parser():
         help="name mirror files so a FAT32 device will accept them"
         " (env MUSIC_MIRROR_FAT32_SAFE)",
     )
+    parser.add_argument(
+        "--max-path",
+        type=int,
+        default=int(os.getenv("MUSIC_MIRROR_MAX_PATH", str(MAX_PATH))),
+        help=f"longest path the device will take, counted from its root; Rockbox's"
+        f" MAX_PATH is {MAX_PATH} (env MUSIC_MIRROR_MAX_PATH)",
+    )
+    parser.add_argument(
+        "--device-prefix",
+        default=os.getenv("MUSIC_MIRROR_DEVICE_PREFIX", DEVICE_PREFIX),
+        help="directory the mirror is copied into on the device, whose length comes"
+        " out of the path budget (env MUSIC_MIRROR_DEVICE_PREFIX)",
+    )
     parser.add_argument(
         "--no-prune",
         action="store_true",
@@ -675,6 +766,17 @@ def main(argv=None):
         # A partial pass cannot tell an orphan from a file outside its scope.
         do_prune = False
 
+    # The device's limit covers the whole path it will see, so what the mirror
+    # may spend is that less the directory it gets copied into.
+    budget = max(0, args.max_path - len(args.device_prefix.strip("/")) - 2)
+    if args.fat32_safe:
+        logger.info(
+            "paths are limited to %d characters, from --max-path %d less the %r prefix",
+            budget,
+            args.max_path,
+            args.device_prefix,
+        )
+
     lock = acquire_lock(mirror_root)
     if lock is None:
         logger.error("another pass is already running over %s", mirror_root)
@@ -701,6 +803,7 @@ def main(argv=None):
                 args.dry_run,
                 do_prune,
                 args.fat32_safe,
+                budget,
             )
             if interval is None or stopping:
                 return 1 if failures else 0