Complete the header template across Partnership, Kernel, Deployment and Plugin

Finishes the pass: every script now documents its safeguards, and the deliberate absences in the sourced libraries are recorded so they are not "corrected" later.
2026-08-01 22:44:23 -04:00
parent 5c4f8db497
commit c377ddfcca
24 changed files with 1237 additions and 32 deletions
@@ -13,6 +13,58 @@
 # RAM-speed reads and auto-cleared on reboot.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# A one-line shim: exec php on api_cache_writer.php in the same directory.
+#
+# All logic lives in the PHP, because the payload builders (vv_monitor_*, vv_arrs_*) are PHP
+# functions shared with the API endpoints. Reimplementing them in bash would mean two
+# implementations of the same payload drifting apart.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# A Shim, Not a Program
+#   This file exists only because the scheduler runs shell scripts and the work is PHP. It
+#   deliberately contains no logic — anything added here would be logic the API endpoints
+#   do not share, which is exactly the drift it exists to prevent.
+#
+# Same Builders as the Live API
+#   The cache is written by the same functions that serve a live request, so a cached
+#   response and a ?live=1 response cannot disagree in shape.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+# No Root, No Lock — Deliberate
+#   Writes only to /tmp/vv_cache as whatever user the scheduler runs as, and a stale cache
+#   is self-correcting on the next minute's run. There is no privileged operation to gate
+#   and no state worth locking: a torn cache file is replaced within 60 seconds, and every
+#   reader already falls back to a live call when the cache is missing or unparseable.
+#
+# Failure Is Non-Fatal by Design
+#   If the PHP fails, the cache simply is not refreshed. Pages fall back to live API calls —
+#   slower, but correct. This script must never be able to take the UI down.
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# None. Cache location and payload contents are owned by api_cache_writer.php and
+# include/config.php (VV_CACHE_DIR). Nothing is configurable from this file.
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# api_cache_writer.sh
+#     Refresh the monitor and arrs caches once. No flags — the PHP takes no arguments and
+#     there is nothing to preview, since the only effect is replacing a regenerable cache.
+#
+# ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 php "$SCRIPT_DIR/api_cache_writer.php"
@@ -33,6 +33,25 @@
 #   --delete behaviour automatically. No manual cleanup needed.
 #
 # ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# The .cfg Files Are the Source of Truth
+#   Directories are recreated from /boot/config/shares/*.cfg rather than from a list in
+#   Varaverk's conf. Those files are Unraid's own record of what a share is and which disks
+#   it spans — anything Varaverk maintained separately would be a second copy free to drift.
+#
+# Create Only, Never Delete
+#   Missing directories are created and existing ones left alone. This runs after a rebuild,
+#   when the operator's mental model of what should exist may be out of date; removing
+#   anything on that basis is how a recovery step becomes a data loss step.
+#
+# Array Must Be Started
+#   Refuses to run without /mnt/user mounted. Creating share directories against an
+#   unmounted array writes them into the underlying root filesystem, which then shadows the
+#   real shares once the array does mount.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -58,6 +77,22 @@
 #   platform_require_cmd confirms the notify script is present before use.
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# No Varaverk config vars. Everything is read from Unraid's own share definitions:
+#
+#   /boot/config/shares/*.cfg
+#       One file per share. shareInclude names the disks the share spans; the directory is
+#       created on each of them. A share with no shareInclude spans all array disks.
+#
+#   /mnt/user
+#       Must be mounted — see Array Must Be Started above.
+#
+# Deliberately not driven by HOST*_*_SYNC_SHARES: this recreates every share the server
+# knows about, not only the ones Varaverk syncs.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #
@@ -28,6 +28,22 @@
 #   for the full 2-hour cycle. Keeps the cache fresh when a user requests it.
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+# Per partner host:
+#   1. Resolve its Tailscale IP — unresolvable skips that host, not the run
+#   2. SSH across and call vv_arrs_local_node() on its own PHP stack
+#   3. Write the JSON to /tmp/vv_cache/arrs_remote_<hostid>.json locally
+#
+# The remote builds its own payload rather than this host querying the remote's arr APIs
+# directly — the partner already has working local URLs and keys for its own arrs, so no
+# cross-host credentials or path mapping are involved.
+#
+# Runs every 2 hours. The arrs page reads these files for an instant first paint and falls
+# back to live calls when a file is missing or stale.
+#
+# ==============================================================================================
 # OPERATIONAL SAFEGUARDS
 # ==============================================================================================
 #
@@ -37,6 +53,24 @@
 #   /tmp/vv_cache/  — auto-created if missing; cleared on reboot (intentional)
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# host*.conf
+#
+#   SSH_KEY
+#       Used to reach each partner. Written by ssh_setup.sh.
+#
+#   HOST*  — partner hostnames, resolved to Tailscale IPs at runtime
+#
+# Cache output: /tmp/vv_cache/arrs_remote_<hostid>.json
+#   tmpfs, cleared on reboot. Regenerable by definition — losing it costs one slow page
+#   load, never correctness, which is why nothing here retries hard on failure.
+#
+# No arr credentials are read locally. Each partner uses its own SONARR_*/RADARR_*/LIDARR_*
+# values on its own side, so this host never holds keys for a remote's arrs.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #
@@ -51,6 +85,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../../../load_config.sh"

 parse_args "$@"
+
+# Reads $SSH_KEY from /root/.ssh to reach partner hosts.
+[[ "$EUID" -ne 0 ]] && { error "Must be run as root"; exit 1; }
+
 acquire_lock
 detect_hosts

@@ -24,6 +24,21 @@
 #   varaverk.cron     rebuilt via PHP (job paths regenerated for new SCRIPTS_DIR)
 #
 # ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
+#
+#   1. Determine current mode from varaverk.cfg SCRIPTS_DIR, and the requested target mode
+#      Already in the target mode → exit cleanly, nothing to do
+#   2. rsync -a --delete SRC → DST, then carry .git across so history survives the move
+#   3. Rewrite the pointers, in this order:
+#        varaverk.cfg   SCRIPTS_DIR
+#        master.conf    TARGET_DIR
+#        host*.conf     HOST*_STORAGE_MODE_INTERNAL
+#   4. Rebuild varaverk.cron via PHP so every job path points at the new SCRIPTS_DIR
+#   5. Flash mode only: sync Plugin/ back to /boot so the webUI keeps serving current PHP
+#   6. Remove the old location once the new one is confirmed in place
+#
+# ==============================================================================================
 # DESIGN PRINCIPLES
 # ==============================================================================================
 #
@@ -47,6 +62,31 @@
 #   --to= required  — refuses to run without an explicit target mode
 #
 # ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# This script WRITES these rather than reading them — they are the migration's output:
+#
+#   varaverk.cfg
+#     SCRIPTS_DIR                    the authoritative install path. Everything else in the
+#                                    ecosystem derives from it, which is why it is written
+#                                    first and the cron is rebuilt from it afterwards.
+#
+#   master.conf
+#     TARGET_DIR                     kept in step with SCRIPTS_DIR
+#
+#   host*.conf
+#     HOST*_STORAGE_MODE_INTERNAL    true = /boot/config/plugins/varaverk
+#                                    false = /mnt/user/appdata/Varaverk
+#
+# Load-bearing: STATE_DIR, DATA_DIR, PERSISTENT_CONF_CACHE and the orchestrator job paths are
+# all built from SCRIPTS_DIR. Changing storage mode moves every one of them, which is why the
+# cron is regenerated rather than edited.
+#
+# In flash mode the array must be started before Varaverk can function at all — appdata is
+# not mounted before that.
+#
+# ==============================================================================================
 # RUNTIME MODES
 # ==============================================================================================
 #
@@ -68,6 +108,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/../../../load_config.sh"

 parse_args "$@"
+
+# Relocates the entire Varaverk installation with rsync --delete and rm -rf, and rewrites
+# varaverk.cfg, master.conf and host*.conf. Everything here needs root.
+[[ "$EUID" -ne 0 ]] && { error "Must be run as root"; exit 1; }
+
 acquire_lock
 detect_hosts