#!/bin/bash
# ==============================================================================================
# ================================= API Cache Writer ===========================================
# ==============================================================================================
#
# PURPOSE
# ─────────────────────────────────────────────────────────────────────────────
# Builds the monitor and arrs API payloads and writes them to /tmp/vv_cache/
# so page loads can serve from the file instantly instead of making live HTTP
# calls on every request.
#
# Runs every minute via the Varaverk scheduler. /tmp is tmpfs — files are
# 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"
