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 backup kinds
Juan Denise8e94a126fa5
diff --git a/backend/app/api/backups.py b/backend/app/api/backups.pyindex 5d3628ab..2bd0ed57 100644--- a/backend/app/api/backups.py+++ b/backend/app/api/backups.py@@ -44,7 +44,9 @@ def list_policies():query = BackupPolicy.querytarget_type = request.args.get('target_type')if target_type:- if target_type not in VALID_TARGET_TYPES:+ from app.services import backup_kind_registry+ if (target_type not in VALID_TARGET_TYPES+ and not backup_kind_registry.get(target_type)):return jsonify({'error': f'invalid target_type {target_type!r}'}), 400query = query.filter_by(target_type=target_type)enabled = request.args.get('enabled')diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.pyindex c3f6d51c..a2a23c8e 100644--- a/backend/app/plugins_sdk/__init__.py+++ b/backend/app/plugins_sdk/__init__.py@@ -105,6 +105,7 @@ _LAZY_SURFACES = {'search': ('app.plugins_sdk.search_sdk', 'search'),'store': ('app.plugins_sdk.store_sdk', 'store'),'doctor': ('app.plugins_sdk.doctor_sdk', 'doctor'),+ 'backups': ('app.plugins_sdk.backups_sdk', 'backups'),}_lazy_cache = {}@@ -148,6 +149,7 @@ __all__ = ['search','store','doctor',+ 'backups','permissions','require_permission','panel_version',diff --git a/backend/app/plugins_sdk/backups_sdk.py b/backend/app/plugins_sdk/backups_sdk.pynew file mode 100644index 00000000..9aba0cd9--- /dev/null+++ b/backend/app/plugins_sdk/backups_sdk.py@@ -0,0 +1,65 @@+"""Plugin-facing SDK for backups.++ from app.plugins_sdk import backups++ def resolve(policy):+ world = World.query.get(policy.target_id)+ if not world:+ raise ValueError('World not found')+ return {'name': world.name, 'root_path': world.directory, 'world': world}++ def execute(policy, target, kind):+ path = tar_up(target['root_path'])+ return path, os.path.getsize(path), {'world': target['name']}++ def restore(policy, target, run, options):+ untar(run.storage_path, target['root_path'])++ backups.register('minecraft.world', resolve=resolve, execute=execute,+ restore=restore)++Registering a kind means never writing backup plumbing again: the policy row+and its cron schedule, run history, retention (count and age, aware of+incremental chains), offsite copy, verification, restore, and the Protection+panel — which is already generic over the target type — all come from the+panel. Create a policy the way core does::++ from app.services.backup_policy_service import BackupPolicyService+ BackupPolicyService.get_or_create_policy('minecraft.world', world.id)++Then the operator schedules, runs, prunes and restores it from the UI.++``restore`` is optional but strongly encouraged. Without it the panel refuses+the restore up front and says so, rather than queueing a job that fails — and+critically, rather than falling through to core's application restore, which+would unpack your archive over an app directory.+"""++from app.services import backup_kind_registry+++class BackupsSdk:+ """Stable backup surface for plugins."""++ def register(self, target_type, resolve, execute, restore=None, replace=False):+ """Register a backup target type.++ ``resolve(policy) -> dict`` describes the live target (include+ ``name``, and ``root_path`` if it is a directory); raise if it is gone.+ ``execute(policy, target, kind) -> (storage_path, size_bytes, meta)``+ produces the artifact. ``restore(policy, target, run, options)`` puts+ one back.++ Namespace the type after your plugin (``minecraft.world``); core's bare+ words are reserved.+ """+ return backup_kind_registry.register(+ target_type, resolve=resolve, execute=execute, restore=restore,+ replace=replace)++ def kinds(self):+ """Backup target types registered by plugins."""+ return backup_kind_registry.kinds()+++backups = BackupsSdk()diff --git a/backend/app/services/backup_kind_registry.py b/backend/app/services/backup_kind_registry.pynew file mode 100644index 00000000..852cd7b6--- /dev/null+++ b/backend/app/services/backup_kind_registry.py@@ -0,0 +1,136 @@+"""Registry of backup target types contributed outside the core.++``BackupPolicyService`` dispatches on ``policy.target_type`` through four+hardcoded switches — resolve, execute, restore, and the validator that gates+every API route. An extension therefore could not say "here is a thing of mine+worth backing up", and had to hand-roll its own backups with no policy, no+schedule, no retention, no restore and no place in the Protection panel.++A registered kind inherits all of it: the policy row and its cron mirror, the+BackupRun history, retention (count/days, incremental-chain aware), offsite+copy, verification, the restore flow and the panel UI — which is already+generic over ``target_type`` and needs no frontend change.++A kind supplies:++``resolve(policy) -> dict``+ Describes the live target. Must include ``name``; ``target_type`` is filled+ in for you. Raise if the thing no longer exists.+``execute(policy, target, kind) -> (storage_path, size_bytes, meta)``+ Produces the artifact. ``kind`` is ``'full'`` or ``'incremental'``;+ contributed kinds are always asked for ``'full'`` unless they opt in.+``restore(policy, target, run, options)`` — optional+ Puts a run back. **Without it a restore is refused**, rather than falling+ through to core's application restore, which would unpack a plugin's+ archive over an app directory.+"""++import logging++logger = logging.getLogger(__name__)++# target_type -> {'resolve': fn, 'execute': fn, 'restore': fn|None}+_KINDS = {}+++def core_kinds():+ """The target types core owns (imported lazily to avoid a model import)."""+ from app.models.backup_policy import VALID_TARGET_TYPES+ return VALID_TARGET_TYPES+++def register(target_type: str, resolve, execute, restore=None, replace: bool = False):+ """Register a backup target type.++ Namespace it after your plugin (``minecraft.world``); the bare words core+ uses are reserved.+ """+ if not target_type:+ raise ValueError('a backup kind needs a target type')+ if not callable(resolve) or not callable(execute):+ raise ValueError('a backup kind needs callable resolve and execute functions')+ if restore is not None and not callable(restore):+ raise ValueError('a backup restore must be callable')+ if target_type in core_kinds():+ raise ValueError(f'"{target_type}" is a core backup target type and cannot be overridden')+ if target_type in _KINDS and not replace:+ raise ValueError(f'backup kind "{target_type}" is already registered')+ _KINDS[target_type] = {'resolve': resolve, 'execute': execute, 'restore': restore}+ logger.info('Registered backup kind: %s', target_type)+ return _KINDS[target_type]+++def get(target_type: str):+ """The registration for *target_type*, or None."""+ return _KINDS.get(target_type)+++def kinds():+ """All registered non-core target types."""+ return sorted(_KINDS)+++def clear():+ """Drop every registration. Tests only."""+ _KINDS.clear()+++def resolve(policy):+ """Resolve a contributed target, normalising what the plugin returns."""+ entry = _require(policy.target_type)+ target = entry['resolve'](policy)+ if not isinstance(target, dict):+ raise ValueError(+ f'backup kind "{policy.target_type}" resolve() must return a dict')+ target.setdefault('name', f'{policy.target_type}:{policy.target_id}')+ # Forced, not defaulted: every downstream branch keys off this, and a kind+ # that claimed to be 'application' would be restored as one.+ target['target_type'] = policy.target_type+ target.setdefault('root_path', None)+ target.setdefault('app', None)+ return target+++def execute(policy, target, kind):+ """Run a contributed backup, normalising its return value."""+ entry = _require(policy.target_type)+ result = entry['execute'](policy, target, kind)+ try:+ storage_path, size, meta = result+ except (TypeError, ValueError) as exc:+ raise ValueError(+ f'backup kind "{policy.target_type}" execute() must return '+ '(storage_path, size, meta)') from exc+ if not storage_path:+ raise ValueError(+ f'backup kind "{policy.target_type}" execute() returned no storage path')+ meta = dict(meta or {})+ meta.setdefault('engine', policy.target_type)+ # Contributed kinds are asked for 'full' and retention protects incremental+ # chains by ancestry, so record what actually happened rather than assuming.+ meta.setdefault('kind', kind or 'full')+ meta.setdefault('incremental', meta['kind'] == 'incremental')+ return storage_path, int(size or 0), meta+++def restore(policy, target, run, options):+ """Restore a contributed run, or refuse if the kind can't."""+ entry = _require(policy.target_type)+ handler = entry.get('restore')+ if handler is None:+ raise ValueError(+ f'backup kind "{policy.target_type}" does not support restore')+ return handler(policy, target, run, options or {})+++def supports_restore(target_type: str) -> bool:+ """True if *target_type* is registered and can restore."""+ entry = _KINDS.get(target_type)+ return bool(entry and entry.get('restore'))+++def _require(target_type):+ entry = _KINDS.get(target_type)+ if entry is None:+ raise ValueError(f'No backup kind registered for "{target_type}"')+ return entrydiff --git a/backend/app/services/backup_policy_service.py b/backend/app/services/backup_policy_service.pyindex d0f41b3d..0c310794 100644--- a/backend/app/services/backup_policy_service.py+++ b/backend/app/services/backup_policy_service.py@@ -51,12 +51,21 @@ class BackupPolicyService:@staticmethoddef validate_target_type(target_type):- """Reject unknown target types (maps to HTTP 400)."""+ """Reject unknown target types (maps to HTTP 400).++ Every policy route funnels through here, so accepting a registered+ plugin kind is what opens the whole blueprint — and the Protection+ panel, which is already generic over target_type — to it.+ """from app.models.backup_policy import VALID_TARGET_TYPES- if target_type not in VALID_TARGET_TYPES:- raise BackupPolicyError(- f"target_type must be one of {VALID_TARGET_TYPES}, got {target_type!r}"- )+ if target_type in VALID_TARGET_TYPES:+ return+ from app.services import backup_kind_registry+ if backup_kind_registry.get(target_type):+ return+ raise BackupPolicyError(+ f"target_type must be one of {VALID_TARGET_TYPES}, got {target_type!r}"+ )@classmethoddef get_or_create_policy(cls, target_type, target_id, target_subtype=None, target_meta=None):@@ -205,6 +214,12 @@ class BackupPolicyService:keys: name, root_path, target_type, site (wp only), app, plusdb_config (database) / file_paths (files) for the non-resource targets."""+ # Checked first, and before the application fallthrough at the bottom:+ # an unrecognised type there is treated as an application.+ from app.services import backup_kind_registry+ if backup_kind_registry.get(policy.target_type):+ return backup_kind_registry.resolve(policy)+if policy.target_type == 'wordpress_site':from app.models.wordpress_site import WordPressSitesite = WordPressSite.query.get(policy.target_id)@@ -361,6 +376,10 @@ class BackupPolicyService:"""Produce a backup for the target. Returns (storage_path, size, metadata).The actual kind used is metadata['kind'] (a tar fallback can downgrade anincremental to a full). Raises on failure."""+ from app.services import backup_kind_registry+ if backup_kind_registry.get(target['target_type']):+ return backup_kind_registry.execute(policy, target, kind)+meta = {'engine': target['target_type']}if target['target_type'] == 'wordpress_site':from app.services.wordpress_bridge import wordpress_service@@ -660,6 +679,14 @@ class BackupPolicyService:raise BackupPolicyError('Only a successful backup can be restored')if cls.is_running(policy):raise BackupPolicyError('A backup or restore is already in progress.')+ from app.services import backup_kind_registry+ if (backup_kind_registry.get(policy.target_type)+ and not backup_kind_registry.supports_restore(policy.target_type)):+ # Answer here rather than by queueing a job that will fail: the+ # kind's own author decided not to implement restore.+ raise BackupPolicyError(+ f'Backups of type "{policy.target_type}" cannot be restored '+ 'from the panel.')payload = {'policy_id': policy.id,'run_id': run_id,@@ -697,7 +724,12 @@ class BackupPolicyService:except Exception as exc: # safety backup is best-effortlogger.warning('Safety backup before restore failed: %s', exc)- if target['target_type'] == 'wordpress_site':+ from app.services import backup_kind_registry+ if backup_kind_registry.get(target['target_type']):+ # Ahead of the else-branch below, which would otherwise unpack+ # a plugin's archive over an application directory.+ backup_kind_registry.restore(policy, target, run, payload)+ elif target['target_type'] == 'wordpress_site':cls._restore_wordpress(target, run, scope, payload)elif target['target_type'] == 'database':cls._restore_database(target, run)diff --git a/backend/tests/test_plugin_backups_sdk.py b/backend/tests/test_plugin_backups_sdk.pynew file mode 100644index 00000000..fd27e1eb--- /dev/null+++ b/backend/tests/test_plugin_backups_sdk.py@@ -0,0 +1,227 @@+"""Backup target types contributed by plugins (plugins_sdk.backups).++An extension with something worth backing up had to hand-roll it: no policy, no+schedule, no retention, no restore, no place in the Protection panel. A+registered kind inherits all of that, because everything downstream of the four+target_type switches — the run lifecycle, retention, the API blueprint, the+panel — is already generic.++The switch this file cares most about is restore: an unrecognised type falls+through to core's application restore, which would unpack a plugin's archive+over an app directory.+"""++import pytest++from app import db+from app.models.backup_policy import BackupPolicy+from app.models.backup_run import BackupRun+from app.services import backup_kind_registry+from app.services.backup_policy_service import BackupPolicyError, BackupPolicyService++[email protected](autouse=True)+def _clean_registry():+ backup_kind_registry.clear()+ yield+ backup_kind_registry.clear()+++def _resolve(policy):+ return {'name': 'Overworld', 'root_path': '/srv/worlds/1'}+++def _execute(policy, target, kind):+ return '/var/backups/world-1.tar.gz', 4096, {'world': target['name']}+++def _register(**over):+ kwargs = {'resolve': _resolve, 'execute': _execute}+ kwargs.update(over)+ return backup_kind_registry.register('minecraft.world', **kwargs)+++def _policy(app, target_type='minecraft.world', target_id=1):+ policy = BackupPolicy(target_type=target_type, target_id=target_id, enabled=True)+ db.session.add(policy)+ db.session.commit()+ return policy+++class TestRegistry:+ def test_registers_and_resolves(self):+ entry = _register()+ assert backup_kind_registry.get('minecraft.world') is entry+ assert backup_kind_registry.kinds() == ['minecraft.world']++ def test_core_kinds_cannot_be_hijacked(self, app):+ for target_type in backup_kind_registry.core_kinds():+ with pytest.raises(ValueError):+ backup_kind_registry.register(target_type, _resolve, _execute)++ def test_duplicate_registration_needs_replace(self, app):+ _register()+ with pytest.raises(ValueError):+ _register()+ _register(replace=True)++ def test_requires_resolve_and_execute(self, app):+ with pytest.raises(ValueError):+ backup_kind_registry.register('minecraft.world', 'nope', _execute)+ with pytest.raises(ValueError):+ backup_kind_registry.register('minecraft.world', _resolve, None)+ with pytest.raises(ValueError):+ backup_kind_registry.register('minecraft.world', _resolve, _execute,+ restore='nope')+++class TestValidation:+ def test_a_registered_kind_is_accepted_by_the_gate(self, app):+ # The keystone: every policy route funnels through this validator, so+ # passing it is what opens the whole blueprint to a plugin kind.+ with pytest.raises(BackupPolicyError):+ BackupPolicyService.validate_target_type('minecraft.world')++ _register()+ BackupPolicyService.validate_target_type('minecraft.world')++ def test_unknown_types_are_still_rejected(self, app):+ _register()+ with pytest.raises(BackupPolicyError):+ BackupPolicyService.validate_target_type('not.registered')++ def test_core_types_still_pass(self, app):+ for target_type in backup_kind_registry.core_kinds():+ BackupPolicyService.validate_target_type(target_type)++ def test_a_policy_can_be_created_for_a_registered_kind(self, app):+ _register()+ policy = BackupPolicyService.get_or_create_policy('minecraft.world', 7)+ assert policy.id is not None+ assert policy.target_type == 'minecraft.world'+++class TestResolve:+ def test_routes_to_the_plugin_and_forces_the_type(self, app):+ _register(resolve=lambda policy: {'name': 'Overworld',+ 'target_type': 'application'})+ target = BackupPolicyService._resolve_target(_policy(app))+ # A kind claiming to be an application would be restored as one.+ assert target['target_type'] == 'minecraft.world'+ assert target['name'] == 'Overworld'++ def test_fills_in_the_keys_core_branches_read(self, app):+ _register(resolve=lambda policy: {})+ target = BackupPolicyService._resolve_target(_policy(app))+ assert target['name'] == 'minecraft.world:1'+ assert target['root_path'] is None and target['app'] is None++ def test_a_non_dict_is_refused(self, app):+ _register(resolve=lambda policy: 'nope')+ with pytest.raises(ValueError):+ BackupPolicyService._resolve_target(_policy(app))++ def test_an_unregistered_type_still_falls_through_to_core(self, app):+ # Core's fallthrough treats anything unknown as an application; that+ # behaviour must be untouched for types we don't own.+ policy = _policy(app, target_type='application', target_id=424242)+ with pytest.raises(BackupPolicyError):+ BackupPolicyService._resolve_target(policy)+++class TestExecute:+ def test_routes_to_the_plugin(self, app):+ _register()+ policy = _policy(app)+ target = BackupPolicyService._resolve_target(policy)++ path, size, meta = BackupPolicyService._execute_backup(policy, target, 'full')++ assert path == '/var/backups/world-1.tar.gz'+ assert size == 4096+ assert meta['world'] == 'Overworld'++ def test_fills_in_the_metadata_retention_and_the_panel_read(self, app):+ _register()+ policy = _policy(app)+ target = BackupPolicyService._resolve_target(policy)++ _path, _size, meta = BackupPolicyService._execute_backup(policy, target, 'full')++ assert meta['engine'] == 'minecraft.world'+ assert meta['kind'] == 'full'+ assert meta['incremental'] is False++ def test_a_bad_return_shape_is_refused(self, app):+ _register(execute=lambda policy, target, kind: 'just-a-path')+ policy = _policy(app)+ target = BackupPolicyService._resolve_target(policy)+ with pytest.raises(ValueError):+ BackupPolicyService._execute_backup(policy, target, 'full')++ def test_no_storage_path_is_refused(self, app):+ _register(execute=lambda policy, target, kind: (None, 0, {}))+ policy = _policy(app)+ target = BackupPolicyService._resolve_target(policy)+ with pytest.raises(ValueError):+ BackupPolicyService._execute_backup(policy, target, 'full')+++class TestRestore:+ def _successful_run(self, policy):+ run = BackupRun(policy_id=policy.id, kind='full', status='success',+ storage_path='/var/backups/world-1.tar.gz')+ db.session.add(run)+ db.session.commit()+ return run++ def test_restore_routes_to_the_plugin(self, app):+ seen = {}++ def restore(policy, target, run, options):+ seen['run_id'] = run.id+ seen['scope'] = options.get('scope')++ _register(restore=restore)+ policy = _policy(app)+ run = self._successful_run(policy)++ BackupPolicyService._resolve_target(policy)+ backup_kind_registry.restore(+ policy, {'target_type': 'minecraft.world', 'name': 'Overworld'},+ run, {'scope': 'full'})++ assert seen == {'run_id': run.id, 'scope': 'full'}++ def test_a_kind_without_restore_is_refused_before_queueing(self, app):+ # Not merely "the job fails later": queueing it would run the safety+ # backup and take the policy lock for nothing.+ _register()+ policy = _policy(app)+ run = self._successful_run(policy)++ with pytest.raises(BackupPolicyError) as excinfo:+ BackupPolicyService.request_restore(policy, run.id, {})+ assert 'cannot be restored' in str(excinfo.value)++ def test_restore_never_falls_through_to_the_application_branch(self, app):+ # The hazard this whole branch exists to close: core's else-branch+ # unpacks the archive over an app directory.+ _register()+ with pytest.raises(ValueError):+ backup_kind_registry.restore(+ _policy(app), {'target_type': 'minecraft.world'}, None, {})++ def test_supports_restore_reports_the_truth(self, app):+ _register()+ assert backup_kind_registry.supports_restore('minecraft.world') is False+ _register(restore=lambda *a: None, replace=True)+ assert backup_kind_registry.supports_restore('minecraft.world') is True+ assert backup_kind_registry.supports_restore('not.registered') is False+++def test_sdk_is_reachable_from_the_package(app):+ from app import plugins_sdk++ plugins_sdk.backups.register('minecraft.world', resolve=_resolve, execute=_execute)+ assert plugins_sdk.backups.kinds() == ['minecraft.world']