v0.5.0: TrueNAS alert when an update is available
Raises a real alert in the TrueNAS UI bell -- not a log line nobody reads. On by default, checked once a day. install.sh --no-update-alerts turns it off. It does not nag --------------- A release whose CHANGELOG contains only a "### Docs" section changed no code and raises nothing. Anything else raises INFO; a "### Security" section raises WARNING. The CHANGELOG's own section headings are the signal, and a security fix anywhere in the range escalates the whole span -- a docs-only release sitting on top of a security fix still reports as security rather than hiding it. Why an AlertSource and not midclt ---------------------------------- TrueNAS cannot raise an alert from the CLI. midclt exposes only alert.dismiss, alert.list, alert.list_categories, alert.list_policies and alert.restore -- alert CREATION is internal to middlewared, and none of its ~60 one-shot classes is generic enough to reuse. Registering an AlertSource is the only way. It is also the least invasive thing this patch does. The providers and nested modules both APPEND CODE TO STOCK middleware files; the alert source ADDS ONE FILE and modifies none. It is the native mechanism -- the same one every built-in TrueNAS alert uses -- and TrueNAS polls it itself, so there is no cron job and no systemd timer. - Fail-safe: every error path returns None; it cannot take middlewared down. - Read-only: `git ls-remote` plus an HTTPS fetch of the CHANGELOG. It never writes to .git, so it cannot leave root-owned objects behind the way a `git fetch` from middlewared (running as root) would. - Removed by uninstall.sh (mw_patch.revert_all). - It only tells you; it never updates anything. Verified against the real repo and remote, with middlewared stubbed: on v0.4.1, only a README-only v0.4.2 available -> NO ALERT on v0.4.0, v0.4.1 fixed real bugs -> INFO on v0.3.2, v0.3.3 was the password fix -> SECURITY / WARNING 139 tests, ruff and shellcheck -S style clean.
This commit is contained in:
flan
@@ -0,0 +1,211 @@
|
||||
"""TrueNAS alert: a truecloud-patch update is available.
|
||||
|
||||
Installed by patch/apply.sh into middlewared/alert/source/, where middlewared
|
||||
discovers and polls it natively — no cron job, no systemd timer.
|
||||
|
||||
@PATCH_DIR@ is substituted at install time.
|
||||
|
||||
Two rules govern this file:
|
||||
|
||||
1. **It must never break middlewared.** It runs inside the alert framework on a
|
||||
timer. Every failure path returns None (no alert) rather than raising.
|
||||
|
||||
2. **It must not nag.** A release whose CHANGELOG only has a "### Docs" section
|
||||
changed no code, and nobody wants an alert because a README was reworded. The
|
||||
CHANGELOG's own section headings are the signal — see tools/release_notes.py.
|
||||
|
||||
It also never writes to the repository. `git ls-remote` is read-only and the
|
||||
CHANGELOG is fetched over HTTPS, so this cannot leave root-owned objects in .git
|
||||
the way a `git fetch` from middlewared (running as root) would.
|
||||
"""
|
||||
|
||||
import datetime
|
||||
import logging
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import urllib.request
|
||||
|
||||
from middlewared.alert.base import (
|
||||
Alert,
|
||||
AlertCategory,
|
||||
AlertClass,
|
||||
AlertLevel,
|
||||
ThreadedAlertSource,
|
||||
)
|
||||
from middlewared.alert.schedule import IntervalSchedule
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
PATCH_DIR = "@PATCH_DIR@"
|
||||
DISABLED_MARKER = os.path.join(PATCH_DIR, "update_alerts_disabled")
|
||||
|
||||
_TAG_RE = re.compile(r"^v\d+\.\d+\.\d+$")
|
||||
_VERSION_RE = re.compile(r'^VERSION="([^"]+)"', re.M)
|
||||
_GITHUB_RE = re.compile(r"github\.com[:/]([^/]+)/([^/.]+)")
|
||||
|
||||
_TIMEOUT = 20
|
||||
|
||||
|
||||
class TrueCloudPatchUpdateAlertClass(AlertClass):
|
||||
category = AlertCategory.SYSTEM
|
||||
level = AlertLevel.INFO
|
||||
title = "truecloud-patch update available"
|
||||
text = (
|
||||
"truecloud-patch %(current)s is installed; %(latest)s is available.%(summary)s "
|
||||
"Update with: bash %(dir)s/update.sh"
|
||||
)
|
||||
|
||||
|
||||
class TrueCloudPatchSecurityUpdateAlertClass(AlertClass):
|
||||
category = AlertCategory.SYSTEM
|
||||
level = AlertLevel.WARNING
|
||||
title = "truecloud-patch security update available"
|
||||
text = (
|
||||
"truecloud-patch %(current)s is installed; %(latest)s contains a SECURITY "
|
||||
"fix.%(summary)s Update with: bash %(dir)s/update.sh"
|
||||
)
|
||||
|
||||
|
||||
class TrueCloudPatchUpdateAlertSource(ThreadedAlertSource):
|
||||
schedule = IntervalSchedule(datetime.timedelta(hours=24))
|
||||
run_on_backup_node = False
|
||||
|
||||
def check_sync(self):
|
||||
try:
|
||||
return self._check()
|
||||
except Exception:
|
||||
# An alert source must never take middlewared down with it.
|
||||
logger.debug("truecloud-patch update check failed", exc_info=True)
|
||||
return None
|
||||
|
||||
# ── internals ────────────────────────────────────────────────────────────
|
||||
|
||||
def _git(self, *args):
|
||||
return subprocess.run(
|
||||
["git", "-C", PATCH_DIR, *args],
|
||||
capture_output=True, text=True, timeout=_TIMEOUT, check=True,
|
||||
).stdout
|
||||
|
||||
def _check(self):
|
||||
if os.path.exists(DISABLED_MARKER):
|
||||
return None
|
||||
if not os.path.isdir(os.path.join(PATCH_DIR, ".git")):
|
||||
return None
|
||||
|
||||
current = self._installed_version()
|
||||
if not current:
|
||||
return None
|
||||
|
||||
latest = self._latest_release_tag()
|
||||
if not latest:
|
||||
return None
|
||||
|
||||
sys.path.insert(0, os.path.join(PATCH_DIR, "tools"))
|
||||
try:
|
||||
from release_notes import significance, version_tuple
|
||||
finally:
|
||||
sys.path.pop(0)
|
||||
|
||||
if version_tuple(latest) <= version_tuple(current):
|
||||
return None
|
||||
|
||||
level, versions, summary = self._classify(
|
||||
current, latest, significance
|
||||
)
|
||||
|
||||
# Documentation-only releases are not worth an alert. This is the whole
|
||||
# point: nobody should get a notification because a README was reworded.
|
||||
if level == "docs":
|
||||
logger.debug(
|
||||
"truecloud-patch %s -> %s is documentation-only; not alerting",
|
||||
current, latest,
|
||||
)
|
||||
return None
|
||||
|
||||
args = {
|
||||
"current": f"v{current}",
|
||||
"latest": latest,
|
||||
"summary": summary,
|
||||
"dir": PATCH_DIR,
|
||||
}
|
||||
klass = (
|
||||
TrueCloudPatchSecurityUpdateAlertClass if level == "security"
|
||||
else TrueCloudPatchUpdateAlertClass
|
||||
)
|
||||
return Alert(klass, args, key=[current, latest])
|
||||
|
||||
def _installed_version(self):
|
||||
"""The version of the patch actually checked out here."""
|
||||
try:
|
||||
with open(os.path.join(PATCH_DIR, "patch", "apply.sh"), encoding="utf-8") as fh:
|
||||
m = _VERSION_RE.search(fh.read())
|
||||
except OSError:
|
||||
return None
|
||||
return m.group(1) if m else None
|
||||
|
||||
def _latest_release_tag(self):
|
||||
"""Newest plain vX.Y.Z tag on the remote. Read-only: no .git writes.
|
||||
|
||||
Pre-release tags (-rc, -beta) are excluded: git's version sort ranks
|
||||
v0.5.0-rc1 above v0.5.0, so including them would advertise a release
|
||||
candidate as the latest stable.
|
||||
"""
|
||||
try:
|
||||
out = self._git("ls-remote", "--tags", "--refs", "origin")
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
tags = []
|
||||
for line in out.splitlines():
|
||||
parts = line.split("refs/tags/")
|
||||
if len(parts) == 2 and _TAG_RE.match(parts[1].strip()):
|
||||
tags.append(parts[1].strip())
|
||||
if not tags:
|
||||
return None
|
||||
|
||||
return max(tags, key=lambda t: tuple(int(x) for x in t.lstrip("v").split(".")))
|
||||
|
||||
def _classify(self, current, latest, significance):
|
||||
"""(level, versions, one-line summary). Falls back to alerting."""
|
||||
text = self._remote_changelog(latest)
|
||||
if text is None:
|
||||
# Cannot tell whether it matters. Alert rather than risk hiding a
|
||||
# security fix -- but say that we could not tell.
|
||||
return "notable", [], " (could not read the changelog)"
|
||||
|
||||
level, versions, headings = significance(text, current, latest)
|
||||
if level == "docs":
|
||||
return level, versions, ""
|
||||
|
||||
seen, ordered = set(), []
|
||||
for h in headings:
|
||||
if h not in seen:
|
||||
seen.add(h)
|
||||
ordered.append(h.capitalize())
|
||||
detail = ", ".join(ordered)
|
||||
return level, versions, f" Changes: {detail}." if detail else ""
|
||||
|
||||
def _remote_changelog(self, tag):
|
||||
"""CHANGELOG.md at `tag`, over HTTPS. None if it cannot be read."""
|
||||
try:
|
||||
remote = self._git("remote", "get-url", "origin").strip()
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
m = _GITHUB_RE.search(remote)
|
||||
if not m:
|
||||
return None # not a GitHub remote; skip classification
|
||||
|
||||
url = (
|
||||
f"https://raw.githubusercontent.com/{m.group(1)}/{m.group(2)}/"
|
||||
f"{tag}/CHANGELOG.md"
|
||||
)
|
||||
try:
|
||||
with urllib.request.urlopen(url, timeout=_TIMEOUT) as resp: # noqa: S310
|
||||
if resp.status != 200:
|
||||
return None
|
||||
return resp.read().decode("utf-8", "replace")
|
||||
except Exception:
|
||||
return None
|
||||
+40
-1
@@ -32,7 +32,7 @@
|
||||
# Derive PATCH_DIR from this script's location (parent of the patch/ directory).
|
||||
PATCH_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
LOG="$PATCH_DIR/apply.log"
|
||||
VERSION="0.4.2"
|
||||
VERSION="0.5.0"
|
||||
|
||||
# Rotate log at 512 KB to avoid unbounded growth on a system volume.
|
||||
# Keep two prior generations (.1 and .2) so the last three boots are always available.
|
||||
@@ -578,6 +578,40 @@ else:
|
||||
# that is inactive (superseded, or opt-in and off) is ok -- reporting a disabled
|
||||
# opt-in feature as FAIL would make `create_task.py verify` fail on a default
|
||||
# install. `active` says whether the module is doing anything.
|
||||
# ── update-available alert ────────────────────────────────────────────────────
|
||||
# Dropped into middlewared/alert/source/, where middlewared discovers and polls it
|
||||
# natively — no cron, no timer. It only raises an alert for releases that actually
|
||||
# changed something: a docs-only release is ignored (see tools/release_notes.py).
|
||||
alert_ok = False
|
||||
alert_detail = ''
|
||||
_patch_dir = os.path.dirname(os.path.dirname(nested_src))
|
||||
alert_src = os.path.join(os.path.dirname(nested_src), 'alert_source.py')
|
||||
alert_dst = os.path.join(mw_dir, 'alert', 'source', 'truecloud_patch_update.py')
|
||||
|
||||
if os.path.exists(os.path.join(_patch_dir, 'update_alerts_disabled')):
|
||||
alert_detail = 'disabled (update_alerts_disabled)'
|
||||
try:
|
||||
os.unlink(alert_dst)
|
||||
print('OK: Removed update alert (disabled).')
|
||||
except OSError:
|
||||
pass
|
||||
elif not os.path.exists(alert_src):
|
||||
alert_detail = 'alert_source.py not found'
|
||||
print(f'WARNING: {alert_src} missing — no update alert.')
|
||||
else:
|
||||
try:
|
||||
with open(alert_src, encoding='utf-8') as fh:
|
||||
_body = fh.read()
|
||||
# PATCH_DIR is baked in: the alert source must find the repo it belongs to.
|
||||
with open(alert_dst, 'w', encoding='utf-8') as fh:
|
||||
fh.write(_body.replace('@PATCH_DIR@', _patch_dir))
|
||||
alert_ok = True
|
||||
alert_detail = 'update alert installed'
|
||||
print(f'OK: Installed update alert → {alert_dst}')
|
||||
except Exception as e:
|
||||
alert_detail = f'not applied: {e}'
|
||||
print(f'WARNING: could not install update alert: {e}')
|
||||
|
||||
patches = {
|
||||
'providers': {
|
||||
'ok': (not providers_needed) or bool(b2_ok and restic_ok),
|
||||
@@ -589,6 +623,11 @@ patches = {
|
||||
'active': nested_needed,
|
||||
'detail': nested_detail,
|
||||
},
|
||||
'update_alert': {
|
||||
'ok': True, # never a failure: it is a convenience, not a patch
|
||||
'active': alert_ok,
|
||||
'detail': alert_detail,
|
||||
},
|
||||
}
|
||||
payload = {'patched_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime()), 'patches': patches}
|
||||
tmp = status_path + '.tmp'
|
||||
|
||||
@@ -52,7 +52,7 @@ import subprocess
|
||||
import sys
|
||||
import time
|
||||
|
||||
__version__ = "0.4.2"
|
||||
__version__ = "0.5.0"
|
||||
|
||||
_PATCH_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
_STATUS_FILE = os.path.join(_PATCH_DIR, "hook_status.json")
|
||||
|
||||
+12
-2
@@ -37,6 +37,10 @@ NESTED_RELPATHS = [
|
||||
#: The importable module the nested blocks depend on.
|
||||
NESTED_MODULE = ("plugins", "cloud", "_truecloud_nested.py")
|
||||
|
||||
#: The update-available alert source. Not a "patch" (it appends nothing to a stock
|
||||
#: file), but it is a file we install into middlewared and must therefore remove.
|
||||
ALERT_MODULE = ("alert", "source", "truecloud_patch_update.py")
|
||||
|
||||
|
||||
def patch_file(path, block):
|
||||
"""Append `block`, replacing any block we appended before. Idempotent."""
|
||||
@@ -101,8 +105,14 @@ def revert_nested(mw_dir):
|
||||
|
||||
|
||||
def revert_all(mw_dir):
|
||||
"""Undo every patch this project applies."""
|
||||
return revert(mw_dir, NESTED_RELPATHS + PROVIDER_RELPATHS, NESTED_MODULE)
|
||||
"""Undo every patch this project applies, and remove every file it installs."""
|
||||
reverted = revert(mw_dir, NESTED_RELPATHS + PROVIDER_RELPATHS, NESTED_MODULE)
|
||||
try:
|
||||
os.unlink(os.path.join(mw_dir, *ALERT_MODULE))
|
||||
reverted.append(ALERT_MODULE[-1])
|
||||
except OSError:
|
||||
pass
|
||||
return reverted
|
||||
|
||||
|
||||
def find_middlewared_dir():
|
||||
|
||||
Reference in New Issue
Block a user