#!/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"

# Mesh traffic sample. Rides this job because it needs a steady once-a-minute cadence and adding
# a second per-minute cron for one append is more moving parts than the measurement is worth.
# Failure is ignored on purpose: a missed sample costs resolution in one window, and this job's
# actual purpose is the WebGUI cache.
php "$SCRIPT_DIR/mesh_traffic_sample.php" >/dev/null 2>&1 || true

# Retry any mesh chat that could not be delivered when it was sent — a partner being asleep is
# the normal case for the message "my server is going down".
php "$SCRIPT_DIR/node_chat_receive.php" --flush >/dev/null 2>&1 || true