diff --git a/Plugin/unraid/Tools/cert_history.sh b/Plugin/unraid/Tools/cert_history.sh index ca659bc..c73a3e5 100755 --- a/Plugin/unraid/Tools/cert_history.sh +++ b/Plugin/unraid/Tools/cert_history.sh @@ -25,6 +25,40 @@ # own created_on, which is a real date; nothing else is back-filled. # # ============================================================================================== +# DESIGN PRINCIPLES +# ============================================================================================== +# +# History is accumulated, never reconstructed. +# NPM holds only the present, so every past state this file knows about is one it observed at +# the time. Counts start at zero on first run and nothing is back-filled — first_seen is the +# single exception, seeded from NPM's own created_on because that is a real recorded date +# rather than an inference. +# +# A domain is retired on strikes, not on a single bad pass. +# A pass fails for a domain when it is absent from NPM's list or its expiry is already in the +# past — and NPM's list can come back short for reasons that have nothing to do with the +# certificate, such as an API hiccup or a restart mid-pass. CERT_HISTORY_STRIKES consecutive +# failures are required before a domain is retired, and it stays in the store afterwards, so +# one bad read can neither erase months of history nor hide a genuine expiry. +# +# The wrapper holds no logic. +# The work sits next to the NPM client it needs, because token handling lives in +# include/auth.php and a bash reimplementation would be a second copy of the thing most worth +# having only one of. Flags are forwarded verbatim. +# +# ============================================================================================== +# OPERATIONAL SAFEGUARDS +# ============================================================================================== +# +# The store is replaced atomically: temp file, verified, then renamed over the original. A pass +# that fails partway leaves the previous history intact rather than a truncated file — this is +# the only record of what these certificates did, and there is no second copy to restore from. +# +# --dry-run reports every change it would make and writes nothing. --status only reads. +# +# Read-only against NPM. Certificates are observed; nothing here renews, deletes or edits one. +# +# ============================================================================================== # RUNTIME MODES # ============================================================================================== # diff --git a/Plugin/unraid/Tools/npm_access_stats.sh b/Plugin/unraid/Tools/npm_access_stats.sh index eedde8c..f24168e 100755 --- a/Plugin/unraid/Tools/npm_access_stats.sh +++ b/Plugin/unraid/Tools/npm_access_stats.sh @@ -22,6 +22,42 @@ # passes are not counted. Running daily keeps that to whatever NPM rotates in a day. # # ============================================================================================== +# DESIGN PRINCIPLES +# ============================================================================================== +# +# Incremental by byte offset, never a re-read. +# 475 MB across 41 files cannot be parsed on a page load, and re-parsing what was already +# counted would make each pass slower than the last. Each run records where it stopped and +# resumes there, so cost tracks new traffic rather than total traffic. +# +# A rotated log is detected, not assumed. +# A file smaller than the offset already recorded for it means NPM rotated it beneath us, so +# that file's offset restarts at zero and a rotation is counted. The totals are cumulative and +# are never reset by it — what rotated out between two passes is simply not counted, which is +# why this runs often enough to keep that gap to whatever NPM rotates in a day. +# +# Varaverk's own probes are excluded. +# uptime_probe.sh requests every proxied host every minute under Varaverk-Uptime/1.0. Counting +# those would make the monitor the busiest client of everything it monitors. +# +# ============================================================================================== +# OPERATIONAL SAFEGUARDS +# ============================================================================================== +# +# Read-only against NPM. Access logs are read and never rotated, truncated or removed — that is +# NPM's business, and a stats collector that deleted its own inputs would be unrecoverable. +# +# --dry-run parses and reports without writing the store or advancing any offset, so a dry run +# leaves the next real pass with exactly the same work to do. +# +# --reset forgets offsets and totals deliberately. It starts from the current end of each log, +# so it discards history rather than double-counting it. +# +# The store is replaced atomically: written to a temp file, re-read and parsed to prove it is +# valid JSON, then renamed over the original. A pass that dies midway — or produces something +# unparseable — leaves the previous document untouched rather than a truncated one. +# +# ============================================================================================== # RUNTIME MODES # ============================================================================================== # diff --git a/Plugin/unraid/Tools/uptime_probe.sh b/Plugin/unraid/Tools/uptime_probe.sh index 1bfc9c3..d82331f 100755 --- a/Plugin/unraid/Tools/uptime_probe.sh +++ b/Plugin/unraid/Tools/uptime_probe.sh @@ -25,6 +25,39 @@ # that, this monitor becomes fifty thousand requests a day in the logs it reports on. # # ============================================================================================== +# DESIGN PRINCIPLES +# ============================================================================================== +# +# Probe what is served, not what was visited. +# The domain list comes from NPM's own proxy hosts, so a host nobody has requested is measured +# exactly like a busy one. Deriving the list from traffic would leave the quietest hosts — the +# ones most likely to be broken without anyone noticing — permanently unmonitored. +# +# The probe is excluded from the statistics it feeds. +# Every request carries Varaverk-Uptime/1.0, which npm_access_stats.sh filters out. Without +# that the monitor would be the largest single source of traffic in the logs it reports on, +# and every access figure would be measuring this script. +# +# The wrapper holds no logic. +# Flags are forwarded verbatim and nothing is interpreted here. Two places that both know what +# --dry-run means is two places that can disagree about it. +# +# ============================================================================================== +# OPERATIONAL SAFEGUARDS +# ============================================================================================== +# +# UPTIME_PROBE_ENABLED gates the whole run. Off means no probes and no writes. +# +# Bounded per domain by UPTIME_PROBE_TIMEOUT, so an unresponsive host costs one timeout rather +# than stalling the pass — the probes run in parallel, so one slow domain never delays the rest. +# +# --dry-run probes and reports without writing. --status and --events read stored history and +# probe nothing, so neither can alter what it is describing. +# +# Read-only against NPM. The domain list is read; no proxy host, certificate or setting is +# touched by anything in this path. +# +# ============================================================================================== # RUNTIME MODES # ============================================================================================== #