ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(plugins): let extensions contribute doctor checks
Juan Denis7e051ddac673
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.pyindex cf6ae0b3..c3f6d51c 100644--- a/backend/app/plugins_sdk/__init__.py+++ b/backend/app/plugins_sdk/__init__.py@@ -104,6 +104,7 @@ _LAZY_SURFACES = {'deploys': ('app.plugins_sdk.deploys_sdk', 'deploys'),'search': ('app.plugins_sdk.search_sdk', 'search'),'store': ('app.plugins_sdk.store_sdk', 'store'),+ 'doctor': ('app.plugins_sdk.doctor_sdk', 'doctor'),}_lazy_cache = {}@@ -146,6 +147,7 @@ __all__ = ['deploys','search','store',+ 'doctor','permissions','require_permission','panel_version',diff --git a/backend/app/plugins_sdk/doctor_sdk.py b/backend/app/plugins_sdk/doctor_sdk.pynew file mode 100644index 00000000..25309cff--- /dev/null+++ b/backend/app/plugins_sdk/doctor_sdk.py@@ -0,0 +1,61 @@+"""Plugin-facing SDK for health checks.++ from app.plugins_sdk import doctor++ def check_worlds():+ stale = [w for w in World.query.all() if w.backup_age_days > 7]+ if not stale:+ return {'key': 'backups', 'title': 'World backups',+ 'status': 'ok', 'detail': 'Every world backed up this week.'}+ return {'key': 'backups', 'title': 'World backups are stale',+ 'status': 'warn',+ 'detail': f'{len(stale)} world(s) have no backup in 7 days.',+ 'repairable': True, 'repair_ref': {'worlds': [w.id for w in stale]}}++ def back_up(ref):+ for world_id in ref['worlds']:+ back_up_world(world_id)+ return {'success': True, 'message': 'Backed up.'}++ doctor.register('minecraft', check_worlds, repair=back_up)++An extension that can say it is unhealthy — on the page the operator already+opens to ask that question — is worth much more than one that can't. A+registered check appears in the sweep with core's, and the panel renders it+without a frontend change.++A check is ``{'key', 'title', 'status', 'detail'}`` where status is ``ok``,+``warn`` or ``fail``. Return one, or a list. Keys are namespaced for you.++Pass ``repair`` to get a Repair button wired to your handler; a check that+claims to be repairable without one is demoted rather than shown as a button+that does nothing. Your provider runs with a time budget (10s by default) and+its own error boundary, so a slow or broken check degrades to a warning instead+of taking the whole sweep with it.+"""++from app.services import doctor_check_registry+++class DoctorSdk:+ """Stable health-check surface for plugins."""++ #: Statuses the panel can render.+ STATUSES = doctor_check_registry.VALID_STATUSES++ def register(self, namespace, provider, repair=None,+ timeout=doctor_check_registry.DEFAULT_TIMEOUT, replace=False):+ """Register ``provider() -> check | [check, ...]`` under *namespace*.++ Namespace after your plugin (``minecraft``); core's own namespaces are+ reserved. *repair* is ``fn(ref) -> {'success': bool, ...}``.+ """+ return doctor_check_registry.register(+ namespace, provider, repair=repair, timeout=timeout, replace=replace)++ def namespaces(self):+ """Namespaces registered by plugins."""+ return doctor_check_registry.namespaces()+++doctor = DoctorSdk()diff --git a/backend/app/services/doctor_check_registry.py b/backend/app/services/doctor_check_registry.pynew file mode 100644index 00000000..a7f9e8af--- /dev/null+++ b/backend/app/services/doctor_check_registry.py@@ -0,0 +1,212 @@+"""Registry of doctor checks contributed outside the core.++``DoctorService.run`` is a fixed sequence of core producers, so an extension had+nowhere to say "the thing I manage is unhealthy, and here is what to do about+it" — the panel's own diagnostics page simply didn't know it existed. A+registered provider is swept with the rest, and the doctor panel renders+whatever it receives (its status pill, repair button and diff toggle all key off+fields, not off a known list of check ids), so a contributed check needs no+frontend work.++Two things this registry does that core's own producers do not:++* **Isolation.** ``run()`` calls its producers bare — each one carries its own+ try/except by hand, and anything that escapes 500s the whole sweep. A+ third-party provider gets a real boundary here: raise, and you become one+ ``warn`` check attributed to your plugin, with the sweep unharmed.+* **A time budget.** Nothing bounds a core producer today, so a hung one hangs+ ``POST /doctor/run`` for whoever asked. A provider that overruns is reported+ as a ``warn`` and the sweep moves on.++Providers run in a worker thread with the app context carried across, so they+can use the database as normal.+"""++import logging+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeout++logger = logging.getLogger(__name__)++# namespace -> {'provider': fn, 'repair': fn|None, 'timeout': float}+_PROVIDERS = {}++#: Seconds one provider may take before the sweep gives up on it.+DEFAULT_TIMEOUT = 10.0++#: The statuses the panel knows how to render. Anything else is reported as a+#: warning rather than passed through as an unrenderable pill.+VALID_STATUSES = ('ok', 'warn', 'fail')++# Prefixes core owns. A contributed check is prefixed with its own namespace, so+# these are unreachable by construction — the guard is here to catch a+# namespace that would collide before it can shadow a core check.+CORE_NAMESPACES = ('drift', 'service', 'dns', 'certs', 'disk', 'db',+ 'setup', 'backup_drill_stale', 'backup_unverified')+++def register(namespace: str, provider, repair=None, timeout: float = DEFAULT_TIMEOUT,+ replace: bool = False):+ """Register ``provider() -> check | [check, ...]`` under *namespace*.++ Each check is ``{'key', 'title', 'status', 'detail'}`` with optional+ ``repairable``/``repair_ref``; keys are prefixed with the namespace so they+ cannot collide with another plugin's or with core's.++ Pass *repair* — ``fn(ref) -> {'success': bool, ...}`` — to make checks+ repairable. Without it, a check claiming ``repairable`` is demoted: the+ panel would otherwise show a button that dispatches nowhere.+ """+ if not namespace or not callable(provider):+ raise ValueError('a doctor check needs a namespace and a callable provider')+ if namespace in CORE_NAMESPACES:+ raise ValueError(f'"{namespace}" is a core doctor namespace and cannot be overridden')+ if repair is not None and not callable(repair):+ raise ValueError('a doctor repair must be callable')+ if namespace in _PROVIDERS and not replace:+ raise ValueError(f'doctor checks for "{namespace}" are already registered')+ _PROVIDERS[namespace] = {'provider': provider, 'repair': repair,+ 'timeout': float(timeout)}+ logger.info('Registered doctor checks: %s', namespace)+ return provider+++def get(namespace: str):+ """The registration for *namespace*, or None."""+ return _PROVIDERS.get(namespace)+++def namespaces():+ """All registered namespaces."""+ return sorted(_PROVIDERS)+++def clear():+ """Drop every registration. Tests only."""+ _PROVIDERS.clear()+++def collect():+ """Run every registered provider and return normalised checks."""+ checks = []+ for namespace in sorted(_PROVIDERS):+ checks.extend(_collect_one(namespace, _PROVIDERS[namespace]))+ return checks+++def repair(namespace: str, ref):+ """Dispatch a repair to *namespace*'s handler."""+ entry = _PROVIDERS.get(namespace)+ if not entry or not entry.get('repair'):+ return {'success': False,+ 'error': f'No doctor repair registered for "{namespace}"'}+ try:+ result = entry['repair'](ref) or {}+ except Exception as exc: # noqa: BLE001 — third-party code+ logger.exception('doctor repair for %s raised', namespace)+ return {'success': False, 'error': str(exc)}+ if not isinstance(result, dict):+ return {'success': bool(result)}+ result.setdefault('success', False)+ return result+++# --------------------------------------------------------------------------- #+# Internals+# --------------------------------------------------------------------------- #++def _collect_one(namespace, entry):+ try:+ raw = _call_with_timeout(entry['provider'], entry['timeout'])+ except FutureTimeout:+ # The thread may still be running — we cannot kill it, but the sweep+ # must not wait on it. Say so rather than reporting a false 'ok'.+ logger.warning('doctor checks for %s exceeded %.1fs', namespace, entry['timeout'])+ return [_warn(namespace, 'timeout',+ f'{namespace} checks timed out',+ f'The check did not finish within {entry["timeout"]:.1f}s '+ 'and was abandoned.')]+ except Exception as exc: # noqa: BLE001 — third-party code+ logger.exception('doctor checks for %s raised', namespace)+ return [_warn(namespace, 'error', f'{namespace} checks failed',+ f'The check raised: {exc}')]++ if isinstance(raw, dict):+ raw = [raw]+ if not isinstance(raw, (list, tuple)):+ return []++ checks = []+ for item in raw:+ cleaned = _clean(namespace, item, repairable=bool(entry.get('repair')))+ if cleaned:+ checks.append(cleaned)+ return checks+++def _call_with_timeout(provider, timeout):+ """Run *provider* under a wall-clock cap, carrying the app context over."""+ try:+ from flask import current_app+ app = current_app._get_current_object()+ except Exception:+ app = None++ def _invoke():+ if app is None:+ return provider()+ with app.app_context():+ return provider()++ pool = ThreadPoolExecutor(max_workers=1)+ try:+ return pool.submit(_invoke).result(timeout=timeout)+ finally:+ # wait=False, deliberately: an overrunning provider is still running and+ # cannot be killed from here, but the sweep must not block on it —+ # which is what the executor's own context manager would do on exit,+ # making the timeout above worthless.+ pool.shutdown(wait=False)+++def _clean(namespace, item, repairable):+ """Normalise one contributed check, or None if it isn't usable."""+ if not isinstance(item, dict):+ return None+ key = str(item.get('key') or '').strip()+ title = str(item.get('title') or '').strip()+ if not key or not title:+ return None++ status = item.get('status')+ if status not in VALID_STATUSES:+ # An unrenderable status would show as a blank pill; a plugin bug+ # should be visible, not invisible.+ status = 'warn'++ check = {+ 'key': key if key.startswith(f'{namespace}.') else f'{namespace}.{key}',+ 'title': title,+ 'detail': str(item.get('detail') or ''),+ 'status': status,+ 'repairable': False,+ 'repair_ref': None,+ 'plugin': namespace,+ }++ if item.get('repairable') and item.get('repair_ref') is not None:+ if repairable:+ # Wrapped, so DoctorService.repair can route it back here without+ # letting a plugin ref impersonate a core repair kind.+ check['repairable'] = True+ check['repair_ref'] = {'kind': 'extension', 'namespace': namespace,+ 'ref': item['repair_ref']}+ else:+ logger.warning('doctor: %s marked a check repairable but registered '+ 'no repair handler', namespace)+ return check+++def _warn(namespace, suffix, title, detail):+ return {'key': f'{namespace}.{suffix}', 'title': title, 'status': 'warn',+ 'detail': detail, 'repairable': False, 'repair_ref': None,+ 'plugin': namespace}diff --git a/backend/app/services/doctor_service.py b/backend/app/services/doctor_service.pyindex 48fe0d5f..96dbb0c4 100644--- a/backend/app/services/doctor_service.py+++ b/backend/app/services/doctor_service.py@@ -466,6 +466,19 @@ class DoctorService:logger.warning('setup-health doctor section failed: %s', e)return []+ @classmethod+ def _extension_checks(cls):+ """Checks contributed by extensions (see doctor_check_registry).++ The registry owns the per-provider isolation and time budget, so a+ third-party check can't take the sweep down with it."""+ try:+ from app.services import doctor_check_registry+ return list(doctor_check_registry.collect())+ except Exception as e: # noqa: BLE001+ logger.warning('extension doctor section failed: %s', e)+ return []+# ------------------------------------------------------------------ ## Sweep# ------------------------------------------------------------------ #@@ -485,6 +498,7 @@ class DoctorService:checks.append(cls._disk_check())checks.append(cls._db_check())checks += cls._setup_checks()+ checks += cls._extension_checks()report = {'checks': checks,'ran_at': datetime.utcnow().isoformat() + 'Z',@@ -534,6 +548,13 @@ class DoctorService:results.append({'item': item, **cls._restart_service(item.get('name'))})elif kind == 'dns':results.append({'item': item, **cls._repair_dns(item.get('host'))})+ elif kind == 'extension':+ # Routed back to the plugin that contributed the check. The+ # registry is the allowlist: an unregistered namespace can't be+ # repaired, so a crafted ref reaches nothing.+ from app.services import doctor_check_registry+ results.append({'item': item, **doctor_check_registry.repair(+ item.get('namespace'), item.get('ref'))})else:results.append({'item': item, 'success': False,'error': f'Unknown repair kind: {kind}'})diff --git a/backend/tests/test_plugin_doctor_sdk.py b/backend/tests/test_plugin_doctor_sdk.pynew file mode 100644index 00000000..650f5a23--- /dev/null+++ b/backend/tests/test_plugin_doctor_sdk.py@@ -0,0 +1,212 @@+"""Doctor checks contributed by plugins (plugins_sdk.doctor).++An extension had no way to say "the thing I manage is unhealthy" on the page an+operator opens to ask exactly that. Registering a provider puts its checks in+the sweep, and the panel renders them with no frontend change.++Core's own producers each hand-roll their isolation and nothing bounds their+runtime; because these run third-party code, the registry adds both — most of+this file is about what happens when a contributed check misbehaves.+"""++import time++import pytest++from app.services import doctor_check_registry+from app.services.doctor_service import DoctorService++[email protected](autouse=True)+def _clean_registry():+ doctor_check_registry.clear()+ yield+ doctor_check_registry.clear()+++def _ok(**over):+ check = {'key': 'worlds', 'title': 'Worlds', 'status': 'ok', 'detail': 'Fine.'}+ check.update(over)+ return check+++def _collect_keys():+ return {c['key']: c for c in doctor_check_registry.collect()}+++class TestRegistry:+ def test_registers_and_resolves(self):+ provider = lambda: []+ doctor_check_registry.register('minecraft', provider)+ assert doctor_check_registry.get('minecraft')['provider'] is provider+ assert 'minecraft' in doctor_check_registry.namespaces()++ def test_core_namespaces_cannot_be_hijacked(self):+ for namespace in doctor_check_registry.CORE_NAMESPACES:+ with pytest.raises(ValueError):+ doctor_check_registry.register(namespace, lambda: [])++ def test_duplicate_registration_needs_replace(self):+ doctor_check_registry.register('minecraft', lambda: [])+ with pytest.raises(ValueError):+ doctor_check_registry.register('minecraft', lambda: [])+ doctor_check_registry.register('minecraft', lambda: [], replace=True)++ def test_rejects_non_callables(self):+ with pytest.raises(ValueError):+ doctor_check_registry.register('minecraft', 'nope')+ with pytest.raises(ValueError):+ doctor_check_registry.register('minecraft', lambda: [], repair='nope')+++class TestCollect:+ def test_namespaces_the_keys(self, app):+ doctor_check_registry.register('minecraft', lambda: _ok())+ assert 'minecraft.worlds' in _collect_keys()++ def test_does_not_double_prefix_an_already_namespaced_key(self, app):+ doctor_check_registry.register('minecraft', lambda: _ok(key='minecraft.worlds'))+ assert list(_collect_keys()) == ['minecraft.worlds']++ def test_accepts_one_check_or_a_list(self, app):+ doctor_check_registry.register('a', lambda: _ok())+ doctor_check_registry.register('b', lambda: [_ok(key='one'), _ok(key='two')])+ assert set(_collect_keys()) == {'a.worlds', 'b.one', 'b.two'}++ def test_drops_checks_missing_a_key_or_title(self, app):+ doctor_check_registry.register(+ 'minecraft', lambda: [{'title': 'no key'}, {'key': 'no-title'}, 'junk'])+ assert _collect_keys() == {}++ def test_unrenderable_status_becomes_a_warning(self, app):+ # A blank pill would hide a plugin bug; a warning shows it.+ doctor_check_registry.register('minecraft', lambda: _ok(status='catastrophe'))+ assert _collect_keys()['minecraft.worlds']['status'] == 'warn'++ def test_attributes_checks_to_their_plugin(self, app):+ doctor_check_registry.register('minecraft', lambda: _ok())+ assert _collect_keys()['minecraft.worlds']['plugin'] == 'minecraft'+++class TestMisbehaviour:+ def test_a_raising_provider_becomes_one_warning(self, app):+ def explode():+ raise RuntimeError('provider is broken')++ doctor_check_registry.register('minecraft', explode)+ checks = doctor_check_registry.collect()++ assert len(checks) == 1+ assert checks[0]['status'] == 'warn'+ assert 'provider is broken' in checks[0]['detail']++ def test_a_hanging_provider_is_abandoned(self, app):+ def hang():+ time.sleep(5)+ return _ok()++ doctor_check_registry.register('minecraft', hang, timeout=0.2)+ started = time.monotonic()+ checks = doctor_check_registry.collect()++ # The sweep must not wait on it — POST /doctor/run is synchronous.+ assert time.monotonic() - started < 3+ assert checks[0]['status'] == 'warn'+ assert 'timed out' in checks[0]['title']++ def test_one_bad_provider_does_not_hide_a_good_one(self, app):+ doctor_check_registry.register('good', lambda: _ok())+ doctor_check_registry.register('bad', lambda: 1 / 0)++ statuses = {c['key']: c['status'] for c in doctor_check_registry.collect()}+ assert statuses['good.worlds'] == 'ok'+ assert statuses['bad.error'] == 'warn'+++class TestRepair:+ def test_repairable_ref_is_wrapped_for_routing(self, app):+ doctor_check_registry.register(+ 'minecraft',+ lambda: _ok(status='warn', repairable=True, repair_ref={'worlds': [1]}),+ repair=lambda ref: {'success': True})++ check = _collect_keys()['minecraft.worlds']+ assert check['repairable'] is True+ assert check['repair_ref'] == {'kind': 'extension', 'namespace': 'minecraft',+ 'ref': {'worlds': [1]}}++ def test_repairable_without_a_handler_is_demoted(self, app):+ # Otherwise the panel shows a button whose dispatch goes nowhere —+ # which is exactly the state two core checks are already in.+ doctor_check_registry.register(+ 'minecraft', lambda: _ok(repairable=True, repair_ref={'worlds': [1]}))++ check = _collect_keys()['minecraft.worlds']+ assert check['repairable'] is False+ assert check['repair_ref'] is None++ def test_doctor_repair_routes_to_the_plugin(self, app):+ seen = {}++ def fix(ref):+ seen['ref'] = ref+ return {'success': True, 'message': 'fixed'}++ doctor_check_registry.register('minecraft', lambda: [], repair=fix)++ results = DoctorService.repair([+ {'kind': 'extension', 'namespace': 'minecraft', 'ref': {'worlds': [7]}}])++ assert results[0]['success'] is True+ assert results[0]['message'] == 'fixed'+ assert seen['ref'] == {'worlds': [7]}++ def test_repair_for_an_unregistered_namespace_is_refused(self, app):+ # The registry IS the allowlist, so a crafted ref reaches nothing.+ results = DoctorService.repair([+ {'kind': 'extension', 'namespace': 'not-installed', 'ref': {}}])+ assert results[0]['success'] is False++ def test_a_raising_repair_reports_failure(self, app):+ def fix(ref):+ raise RuntimeError('could not fix')++ doctor_check_registry.register('minecraft', lambda: [], repair=fix)+ results = DoctorService.repair([+ {'kind': 'extension', 'namespace': 'minecraft', 'ref': {}}])++ assert results[0]['success'] is False+ assert 'could not fix' in results[0]['error']+++class TestSweep:+ def test_contributed_checks_appear_in_the_report(self, app, monkeypatch):+ # Stub the core producers so this test is about the wiring, not about+ # whatever the host machine's nginx is doing.+ for producer in ('_drift_checks', '_service_checks', '_dns_checks',+ '_backup_proof_checks', '_setup_checks'):+ monkeypatch.setattr(DoctorService, producer, classmethod(lambda cls: []))+ for producer in ('_cert_check', '_disk_check', '_db_check'):+ monkeypatch.setattr(DoctorService, producer, classmethod(+ lambda cls: {'key': 'core', 'title': 'Core', 'status': 'ok',+ 'detail': '', 'repairable': False, 'repair_ref': None}))++ doctor_check_registry.register('minecraft', lambda: _ok(status='fail'))++ report = DoctorService.run()++ contributed = [c for c in report['checks'] if c['key'] == 'minecraft.worlds']+ assert len(contributed) == 1+ assert contributed[0]['status'] == 'fail'+ # Every core check carries these six fields and the panel reads them+ # positionally-by-name; a contributed one must be indistinguishable.+ for field in ('key', 'title', 'status', 'detail', 'repairable', 'repair_ref'):+ assert field in contributed[0]+++def test_sdk_is_reachable_from_the_package(app):+ from app import plugins_sdk++ plugins_sdk.doctor.register('minecraft', lambda: _ok())+ assert 'minecraft' in plugins_sdk.doctor.namespaces()+ assert plugins_sdk.doctor.STATUSES == ('ok', 'warn', 'fail')