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
@@ -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