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 backup kinds

Juan Denise8e94a126fa5
diff --git a/backend/app/api/backups.py b/backend/app/api/backups.py
index 5d3628ab..2bd0ed57 100644
--- a/backend/app/api/backups.py
+++ b/backend/app/api/backups.py
@@ -44,7 +44,9 @@ def list_policies():
query = BackupPolicy.query
target_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}'}), 400
query = 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__.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 entry
diff --git a/backend/app/services/backup_policy_service.py b/backend/app/services/backup_policy_service.py
index 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:
@staticmethod
def 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}"
+ )
@classmethod
def 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, plus
db_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 WordPressSite
site = 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 an
incremental 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-effort
logger.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.py
new file mode 100644
index 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']