Skip to content

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.

feat(plugins): let extensions contribute doctor checks

Juan Denis7e051ddac673
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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')