Fix BUG-35: give album release selection size sanity

Dockerfile

@@ -43,11 +43,12 @@ WORKDIR /opt/explo/
 
 # Copy entrypoint, binary, python helper
 COPY ./docker/start.sh /start.sh
+COPY ./docker/explo-run.sh /explo-run.sh
 COPY --from=builder /app/explo .
 COPY src/downloader/youtube_music/search_ytmusic.py .
 
 
-RUN chmod +x /start.sh ./explo
+RUN chmod +x /start.sh /explo-run.sh ./explo
 
 
 ENV WEB_ADDR=":7288"

docker-compose.yaml

@@ -27,6 +27,10 @@ services:
       # Web UI credentials (optional)
       #- UI_USERNAME=
       #- UI_PASSWORD=
+      # Session cookie name. Defaults to explo_session_<port> from WEB_ADDR, so
+      # that instances on one host do not overwrite each other's login. Only set
+      # this if several instances share a host AND port behind a reverse proxy.
+      #- UI_COOKIE_NAME=
 
       # [Legacy] Schedules are managed through the web UI.
       # These can still be set here for backwards compatibility — they will take precedence over the UI.

docker/explo-run.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+# Run one scheduled Explo job under a lock of its own.
+#
+# crond starts a job on schedule whether or not the last one finished, and a run
+# can outlast its own interval -- downloads are slow. Two copies of the same job
+# then race on the same playlist. The lock makes the second one stand down.
+#
+# The lock is per job, not global: a long weekly-exploration must not cancel
+# weekly-jams, since skipping a different playlist entirely is worse than
+# running the two at once.
+#
+# Usage: explo-run.sh <job-name> <command> [args...]
+
+set -u
+
+if [ "$#" -lt 2 ]; then
+    echo "[explo] usage: explo-run.sh <job-name> <command> [args...]" >&2
+    exit 2
+fi
+
+job="$1"
+shift
+
+lock="${EXPLO_LOCK_DIR:-/tmp}/explo-${job}.lock"
+
+# Without flock, run unlocked rather than not at all: an overlapping run is a
+# lesser problem than a playlist that never gets built.
+if ! command -v flock >/dev/null 2>&1; then
+    echo "[explo] $job: flock unavailable, running without an overlap guard"
+    exec "$@"
+fi
+
+# Hold the lock on a file descriptor so it is released when this shell exits,
+# however it exits. Taking it this way also keeps the exit status unambiguous:
+# flock fails here only because the lock is held, never because the job did.
+exec 9>"$lock" || {
+    echo "[explo] $job: couldn't open $lock, running without an overlap guard"
+    exec "$@"
+}
+
+if ! flock -n 9; then
+    echo "[explo] $job: previous run still in progress, skipping this schedule"
+    exit 0
+fi
+
+exec "$@"

docker/explo-run_test.sh

@@ -0,0 +1,86 @@
+#!/bin/sh
+# Tests for explo-run.sh. Run it directly: sh docker/explo-run_test.sh
+#
+# There is no shell test harness in CI (the pipeline runs golangci-lint only),
+# so this is here to be run by hand and to document what the lock guarantees.
+
+set -u
+
+script="$(dirname "$0")/explo-run.sh"
+lockdir="$(mktemp -d)"
+export EXPLO_LOCK_DIR="$lockdir"
+
+failures=0
+
+fail() {
+    echo "FAIL: $1"
+    failures=$((failures + 1))
+}
+
+pass() {
+    echo "ok: $1"
+}
+
+# A job runs normally when nothing holds its lock.
+out="$("$script" solo /bin/echo ran)"
+if [ "$out" = "ran" ]; then
+    pass "runs the command when the lock is free"
+else
+    fail "expected 'ran', got '$out'"
+fi
+
+# A second copy of the SAME job stands down instead of racing the first.
+"$script" overlap /bin/sleep 2 &
+first=$!
+sleep 0.3
+
+out="$("$script" overlap /bin/echo ran)"
+case "$out" in
+    *"skipping this schedule"*)
+        pass "a second copy of the same job skips" ;;
+    *)
+        fail "expected the second run to skip, got '$out'" ;;
+esac
+
+# Skipping must look like success, or cron mails an error every schedule.
+"$script" overlap /bin/echo ran >/dev/null
+if [ $? -eq 0 ]; then
+    pass "a skipped run exits 0"
+else
+    fail "a skipped run exited non-zero"
+fi
+
+# A DIFFERENT job must not be blocked: skipping another playlist entirely is
+# worse than two runs overlapping.
+out="$("$script" other /bin/echo ran)"
+if [ "$out" = "ran" ]; then
+    pass "a different job is not blocked"
+else
+    fail "a different job was blocked, got '$out'"
+fi
+
+wait "$first"
+
+# Once the first finishes, the job can run again.
+out="$("$script" overlap /bin/echo ran)"
+if [ "$out" = "ran" ]; then
+    pass "the lock is released when the run ends"
+else
+    fail "lock was not released, got '$out'"
+fi
+
+# The command's own exit status must reach cron unchanged.
+"$script" status /bin/sh -c 'exit 3'
+if [ $? -eq 3 ]; then
+    pass "the command's exit status is passed through"
+else
+    fail "exit status was not passed through"
+fi
+
+rm -rf "$lockdir"
+
+if [ "$failures" -ne 0 ]; then
+    echo "$failures failure(s)"
+    exit 1
+fi
+echo "all passed"

docker/start.sh

@@ -61,16 +61,23 @@ if [ -f "$_cfg" ]; then
 fi
 
 
-# $CRON_SHCEDULE was deprecated in v0.11.0, keeping this block for backwards compatibility
+# $CRON_SHCEDULE was deprecated in v0.11.0, keeping this block for backwards compatibility.
+# Only register the job here: running `crond -f` in the foreground would block
+# everything below (per-playlist schedules, EXECUTE_ON_START, the final crond),
+# so legacy users silently lost all scheduling.
 if [ -n "$CRON_SCHEDULE" ]; then
-    echo "$CRON_SCHEDULE cd /opt/explo && $RUNNER ./explo --config \"$_cfg\" >> /proc/1/fd/1 2>&1" >> /etc/crontabs/root
+    echo "$CRON_SCHEDULE cd /opt/explo && /explo-run.sh legacy $RUNNER ./explo --config \"$_cfg\" >> /proc/1/fd/1 2>&1" >> /etc/crontabs/root
     chmod 600 /etc/crontabs/root
     echo "[setup] Registered single CRON_SCHEDULE job: $CRON_SCHEDULE"
-    crond -f -l 2
 fi
 
 # Loop over all *_SCHEDULE environment variables
 for var in $(env | grep "_SCHEDULE=" | cut -d= -f1); do
+  # CRON_SCHEDULE is registered by the legacy block above; registering it
+  # again here would run the same job twice.
+  if [ "$var" = "CRON_SCHEDULE" ]; then
+    continue
+  fi
   job="${var%_SCHEDULE}"                     # Job name (e.g WEEKLY_EXPLORATION)
   schedule="$(printenv "$var")"              # Cron schedule
   flags_var="${job}_FLAGS"
@@ -82,7 +89,9 @@ for var in $(env | grep "_SCHEDULE=" | cut -d= -f1); do
   fi
 
   # Default: just run explo if flags are empty
-  cmd="cd /opt/explo && $RUNNER ./explo --config \"$_cfg\" $flags >> /proc/1/fd/1 2>&1"
+  # Wrapped so a run that outlasts its own schedule does not get a second copy
+  # started on top of it. The lock is per job, so other playlists still run.
+  cmd="cd /opt/explo && /explo-run.sh \"$job\" $RUNNER ./explo --config \"$_cfg\" $flags >> /proc/1/fd/1 2>&1"
 
   echo "$schedule $cmd" >> /etc/crontabs/root
   echo "[setup] Registered job: $job"

sample.env

@@ -1,6 +1,10 @@
 # === Web UI ===
 # Web cache limit in MB (cover art, backgrounds) (default: 500)
 # WEB_CACHE_MB=500
+# Kill a run started from the web UI after this many minutes. Without it a
+# wedged run keeps the UI refusing new runs until it is stopped by hand.
+# 0 disables the timeout. (default: 240)
+# RUN_TIMEOUT=240
 
 # === Discovery Config ===
 
@@ -52,6 +56,15 @@ LIBRARY_NAME=
 # KEEP_PERMISSIONS=true
 # Comma-separated list (no spaces) of download services, in priority order (supported: lidarr,slskd,youtube) (default: youtube)
 # DOWNLOAD_SERVICES=youtube
+# Time budget (minutes) for a single download service before Explo gives up on it
+# and lets the next service in DOWNLOAD_SERVICES try the remaining tracks.
+# 0 (default) waits indefinitely. Example chain -- prefer full albums from Lidarr,
+# fall back to slskd for anything it hasn't delivered in 15 minutes:
+#   DOWNLOAD_SERVICES=lidarr,slskd
+#   LIDARR_FALLBACK_AFTER=15
+#   SLSKD_FALLBACK_AFTER=10
+# LIDARR_FALLBACK_AFTER=0
+# SLSKD_FALLBACK_AFTER=0
 # Path templating, Options are Artist, Album, TrackName, TrackNumber, File, Ext (eg. "{{Artist}}/{{Album}}/{{File}}")
 # PATH_TEMPLATE=""
 
@@ -85,6 +98,11 @@ LIBRARY_NAME=
 # SLSKD_MIGRATE_DOWNLOADS=false
 # Overwrite track metadata when moving file (default: false)
 # SLSKD_OVERWRITE_METADATA=false
+# Download the whole release the matched file belongs to instead of just the
+# recommended track. Only the recommended track is added to the playlist; the
+# rest simply land in the library. Off by default -- it multiplies transfer
+# volume per recommendation. (default: false)
+# SLSKD_ALBUM_MODE=false
 # Directory where slskd downloads tracks (default: /slskd/)
 # PS! This is only needed on the binary version, in docker it's set through volume mapping
 # SLSKD_DIR=/slskd/
@@ -101,6 +119,31 @@ LIBRARY_NAME=
 # MIN_BIT_DEPTH=8
 # Minimal Bitrate (default: 256)
 # MIN_BITRATE=256
+# Highest bitrate in kbps to accept, so a single track cannot arrive as a 138 MB
+# WAV. Worked out from file size when a peer reports no bitrate, so it applies
+# to files that describe themselves and files that do not. 0 disables the
+# ceiling. (default: 0)
+# MAX_BITRATE=0
+# Which end of the accepted range to reach for first. "none" leaves the order of
+# EXTENSIONS deciding, as it always has. "smaller" takes the best lossy file and
+# falls back to lossless only when there is none -- note it still prefers a 320
+# over a 256, since wanting a small file does not mean wanting a bad one.
+# "larger" is the reverse. Ranking only; nothing is rejected. (default: none)
+# SIZE_PREFERENCE=none
+# Which release album mode takes when several match. "smaller" takes the one
+# closest to the album's real track count, so a 21-track deluxe edition does
+# not arrive in place of the 11-track album -- note this needs
+# ENRICH_TRACK_METADATA, since that is where the real track count comes from,
+# and falls back to "fuller" without it. "fuller" takes the most complete
+# directory, as it always has. (default: smaller)
+# RELEASE_PREFERENCE=smaller
+# Trim a release down to the original album before downloading it. Extra discs a
+# peer has flattened into one directory are dropped (a real double album is kept
+# whole when ENRICH_TRACK_METADATA confirms it), and bonus tracks appended past
+# the album's real length are dropped after them. The recommended track is always
+# kept, even when it is itself a bonus track. Set to false to take releases
+# exactly as the peer shares them. (default: true)
+# PREFER_ORIGINAL_RELEASE=true
 # Comma-separated (without spaces) keywords to avoid, when filtering slskd results (default: live,remix,instrumental,extended,clean,acapella)
 # FILTER_LIST=live,remix,instrumental,extended,clean,acapella