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 plugins own deployment-shaped work

Juan Denis6be60249f0c4
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.py
index 5e592387..5da80134 100644
--- a/backend/app/plugins_sdk/__init__.py
+++ b/backend/app/plugins_sdk/__init__.py
@@ -98,6 +98,10 @@ queue = QueueBusSdk()
notify = NotifySdk()
jobs = JobsSdk()
+# Imported lazily inside the accessor: deploys pulls in the deployment
+# services, which import models, and this module is imported very early.
+_deploys = None
+
def panel_version():
"""The panel's version string (for compat checks inside a plugin)."""
@@ -134,9 +138,31 @@ __all__ = [
'queue',
'notify',
'jobs',
+ 'deploys',
'permissions',
'require_permission',
'panel_version',
'config',
'sockets',
]
+
+
+def __getattr__(name):
+ """Lazily expose ``deploys``.
+
+ The deploy SDK imports the deployment services (and therefore models),
+ while this module is imported early in app setup — binding it eagerly would
+ make plugins_sdk import-order sensitive for everyone, including the plugins
+ that never touch deployments.
+
+ The implementation lives in deploys_sdk.py, not deploys.py: a submodule of
+ that name would be bound as a package attribute on import and shadow this
+ accessor, handing callers the module instead of the SDK instance.
+ """
+ if name == 'deploys':
+ global _deploys
+ if _deploys is None:
+ from app.plugins_sdk.deploys_sdk import deploys as _d
+ _deploys = _d
+ return _deploys
+ raise AttributeError(name)
diff --git a/backend/app/plugins_sdk/deploys_sdk.py b/backend/app/plugins_sdk/deploys_sdk.py
new file mode 100644
index 00000000..48d7612c
--- /dev/null
+++ b/backend/app/plugins_sdk/deploys_sdk.py
@@ -0,0 +1,109 @@
+"""Plugin-facing SDK for deployment-shaped work.
+
+ from app.plugins_sdk import deploys
+
+ def promote(job):
+ with deploys.steps(job) as step:
+ with step('Snapshot source'):
+ ...
+ with step('Sync files'):
+ ...
+ return {'success': True}
+
+ deploys.register('wordpress.promote', promote)
+ deploys.start('wordpress.promote', steps=['Snapshot source', 'Sync files'],
+ app_id=site.application_id)
+
+Use this — rather than ``plugins_sdk.jobs`` — when the work is a *deployment*:
+it takes minutes, changes what is running, can fail halfway, and someone will
+want to watch it. Registering the kind gets the Deploy Console, live logs,
+retry and a row in Deploy Activity with no frontend work at all, because those
+surfaces key off the DeploymentJob rather than off any particular kind.
+
+``plugins_sdk.jobs`` remains right for everything else: short, unattended,
+retryable background work that nobody watches.
+"""
+
+from contextlib import contextmanager
+
+from app import db
+from app.services import deploy_kind_registry
+from app.services.deployment_job_service import DeploymentJobService
+from app.services.run_log_service import RunLogStream
+
+
+class DeploysSdk:
+ """Stable deployment surface for plugins."""
+
+ def register(self, kind, handler, replace=False):
+ """Register ``handler(job) -> {'success': bool, ...}`` for *kind*.
+
+ Namespace the kind after your plugin (``wordpress.promote``); bare
+ names are reserved for core.
+ """
+ return deploy_kind_registry.register(kind, handler, replace=replace)
+
+ def start(self, kind, *, steps=None, app_id=None, server_id=None,
+ user_id=None, trigger='manual', plan=None, wait=False):
+ """Queue a deployment of *kind* and return ``{'success', 'job_id'}``.
+
+ ``steps`` are the names the console shows, in order; the returned
+ ``job_id`` addresses ``/deployments/<id>`` immediately, so a caller can
+ redirect there before the work begins.
+ """
+ return DeploymentJobService.start_registered(
+ kind, steps=steps, app_id=app_id, server_id=server_id,
+ user_id=user_id, trigger=trigger, plan=plan, wait=wait,
+ )
+
+ def kinds(self):
+ """Deployment kinds registered by plugins."""
+ return deploy_kind_registry.kinds()
+
+ # ---------------------------------------------------------------- logging
+
+ def log(self, job, message, level='info', step_index=None):
+ """Append one line to a job's console."""
+ stream = RunLogStream.for_job(job)
+ stream.log(level, message, step_index=step_index)
+ stream.flush()
+
+ @contextmanager
+ def steps(self, job):
+ """Walk a job's steps, keeping progress and logs in step.
+
+ Yields a ``step(name)`` context manager. Entering advances the job's
+ current step (so the console's pipeline strip lights up and the
+ activity feed's tick bar fills); leaving normally logs completion,
+ while an exception records which step failed before propagating —
+ without that, a failure shows only a stack trace and no indication of
+ how far the deployment got.
+ """
+ stream = RunLogStream.for_job(job)
+ state = {'index': 0}
+
+ @contextmanager
+ def step(name):
+ state['index'] += 1
+ index = state['index']
+ job.current_step = index
+ job.current_step_name = name
+ db.session.commit()
+ stream.log('info', f'→ {name}', step_index=index)
+ stream.flush()
+ try:
+ yield index
+ except Exception as exc:
+ stream.log('error', f'{name} failed: {exc}', step_index=index)
+ stream.flush()
+ raise
+ stream.log('info', f'✓ {name}', step_index=index)
+ stream.flush()
+
+ try:
+ yield step
+ finally:
+ stream.flush()
+
+
+deploys = DeploysSdk()
diff --git a/backend/app/services/deploy_kind_registry.py b/backend/app/services/deploy_kind_registry.py
new file mode 100644
index 00000000..edd0c086
--- /dev/null
+++ b/backend/app/services/deploy_kind_registry.py
@@ -0,0 +1,57 @@
+"""Registry of deployment-job kinds contributed outside the core.
+
+``DeploymentJobService.run_job`` dispatches on ``job.kind`` through a hardcoded
+switch — fine while every kind lived in core (app_deploy, template_install,
+demo_deploy), but it meant a plugin could not own long-running work that
+*behaves* like a deployment. Plugin work had to go to the generic job system
+instead, which gives no step plan, no streaming console, and no place in Deploy
+Activity. WordPress is the case in point: promoting an environment is
+deploy-shaped in every respect, yet it was invisible in the one page users open
+to see what ran.
+
+A registered kind gets all of that for free: a DeploymentJob row, the Deploy
+Console with live logs, retry, and a row in the activity feed — with no
+frontend work, because the feed already renders unknown kinds by their id.
+
+Handlers receive the ``DeploymentJob`` and return the same
+``{'success': bool, ...}`` shape core handlers use.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# kind -> handler(job) -> dict
+_HANDLERS = {}
+
+# Kinds contributed here are namespaced by convention (``wordpress.promote``)
+# so they cannot collide with the core kinds, which are bare words.
+CORE_KINDS = ('app_deploy', 'template_install', 'demo_deploy')
+
+
+def register(kind: str, handler, replace: bool = False):
+ """Register *handler* for deployment-job *kind*."""
+ if not kind or not callable(handler):
+ raise ValueError('deploy kind requires a name and a callable handler')
+ if kind in CORE_KINDS:
+ raise ValueError(f'"{kind}" is a core deployment kind and cannot be overridden')
+ if kind in _HANDLERS and not replace:
+ raise ValueError(f'deploy kind "{kind}" is already registered')
+ _HANDLERS[kind] = handler
+ logger.info('Registered deployment kind: %s', kind)
+ return handler
+
+
+def get(kind: str):
+ """Return the handler for *kind*, or None."""
+ return _HANDLERS.get(kind)
+
+
+def kinds():
+ """All registered non-core kinds."""
+ return sorted(_HANDLERS)
+
+
+def clear():
+ """Drop every registration. Tests only."""
+ _HANDLERS.clear()
diff --git a/backend/app/services/deployment_job_service.py b/backend/app/services/deployment_job_service.py
index 6da9ff5e..b991efae 100644
--- a/backend/app/services/deployment_job_service.py
+++ b/backend/app/services/deployment_job_service.py
@@ -1,5 +1,6 @@
"""Deployment job orchestration service."""
+import logging
import os
import uuid
from datetime import datetime
@@ -9,7 +10,7 @@ from app import db
from app.models import Application, Server
from app.models.deployment_job import DeploymentJob
from app.services.deployment_runner import DeploymentPlanRunner
-from app.services.run_log_service import append_log
+from app.services.run_log_service import append_log, RunLogStream
from app.services.docker_service import DockerService
from app.services.template_service import TemplateService
from app.services.telemetry_service import generate_correlation_id
@@ -20,6 +21,9 @@ from app.services.telemetry_service import generate_correlation_id
JOB_KIND = 'deploy.install'
APP_JOB_KIND = 'deploy.app'
DEMO_JOB_KIND = 'deploy.demo'
+REGISTERED_JOB_KIND = 'deploy.registered'
+
+logger = logging.getLogger(__name__)
class DeploymentJobService:
@@ -171,6 +175,15 @@ class DeploymentJobService:
from app.services.demo_deploy_service import DemoDeployService
return DemoDeployService.run(job)
+ # Kinds contributed by plugins (see deploy_kind_registry). Checked
+ # before the unsupported-kind bail so a plugin's deployment runs through
+ # the same console, retry and activity feed as a core one.
+ if job.kind not in ('app_deploy', 'template_install', 'demo_deploy'):
+ from app.services import deploy_kind_registry
+ handler = deploy_kind_registry.get(job.kind)
+ if handler:
+ return cls._run_registered_kind(job, handler)
+
if job.kind != 'template_install':
return {'success': False, 'error': f'Unsupported deployment job kind: {job.kind}'}
@@ -244,10 +257,16 @@ class DeploymentJobService:
db.session.add(clone)
db.session.commit()
+ from app.services import deploy_kind_registry
enqueue = {
'app_deploy': cls._enqueue_app_deploy,
'demo_deploy': cls._enqueue_demo,
- }.get(clone.kind, cls._enqueue_install)
+ }.get(clone.kind)
+ if enqueue is None:
+ # A registered (plugin) kind retries through its own runner; only a
+ # genuine template_install falls through to the install queue.
+ enqueue = (cls._enqueue_registered if deploy_kind_registry.get(clone.kind)
+ else cls._enqueue_install)
try:
enqueue(clone)
except Exception as exc:
@@ -502,6 +521,119 @@ class DeploymentJobService:
correlation_id=job.correlation_id,
)
+ @classmethod
+ def start_registered(cls, kind: str, *, steps=None, app_id=None, server_id=None,
+ user_id=None, trigger='manual', plan=None, wait=False) -> Dict:
+ """Create and queue a DeploymentJob for a registered (plugin) kind.
+
+ The public entry point behind ``app.plugins_sdk.deploys.start`` — the
+ caller supplies the step names its handler will walk, and gets back a
+ job id that already addresses the Deploy Console.
+ """
+ from app.services import deploy_kind_registry
+ if not deploy_kind_registry.get(kind):
+ return {'success': False, 'error': f'No handler registered for deployment kind "{kind}"'}
+
+ job = DeploymentJob(
+ id=str(uuid.uuid4()),
+ kind=kind,
+ status='pending',
+ app_id=app_id,
+ target_server_id=cls._normalize_server_id(server_id),
+ requested_by=user_id,
+ trigger=trigger,
+ correlation_id=generate_correlation_id(),
+ )
+ job.set_plan({**(plan or {}), 'steps': [{'name': n} for n in (steps or [])]})
+ job.total_steps = len(steps or [])
+ db.session.add(job)
+ db.session.commit()
+
+ if wait:
+ # Ran inline, so report what actually happened rather than merely
+ # that the job was created — a caller passing wait=True is asking
+ # for the outcome.
+ run_result = cls.run_job(job.id)
+ return {**run_result, 'job_id': job.id, 'job': job.to_dict()}
+
+ try:
+ cls._enqueue_registered(job)
+ except Exception as exc:
+ # Same guard as every other producer: never leave a runner-less
+ # 'pending' row behind.
+ db.session.rollback()
+ job.status = 'failed'
+ job.error_message = f'Failed to queue deployment: {exc}'
+ job.completed_at = datetime.utcnow()
+ db.session.commit()
+ return {'success': False, 'error': job.error_message, 'job_id': job.id}
+
+ return {'success': True, 'job_id': job.id, 'job': job.to_dict()}
+
+ @classmethod
+ def _enqueue_registered(cls, job: DeploymentJob):
+ """Hand a plugin-contributed deployment to the unified job system."""
+ from app.jobs.service import JobService
+ return JobService.enqueue(
+ REGISTERED_JOB_KIND,
+ payload={'deployment_job_id': job.id},
+ max_attempts=1,
+ owner_type='deployment_job',
+ owner_id=job.id,
+ correlation_id=job.correlation_id,
+ )
+
+ @staticmethod
+ def _run_registered_job(unified_job):
+ """Unified-job handler for ``deploy.registered``."""
+ deployment_job_id = (unified_job.get_payload() or {}).get('deployment_job_id')
+ if not deployment_job_id:
+ raise ValueError('deploy.registered job missing deployment_job_id')
+ result = DeploymentJobService.run_job(deployment_job_id)
+ if not result.get('success'):
+ raise RuntimeError(result.get('error') or 'Deployment failed')
+ return {'deployment_job_id': deployment_job_id}
+
+ @classmethod
+ def _run_registered_kind(cls, job: DeploymentJob, handler) -> Dict:
+ """Run a plugin-contributed kind, owning the failure path ourselves.
+
+ A plugin handler is third-party code: if it raises, the job must still
+ end up visibly failed rather than stuck at 'running' forever with no
+ explanation — the same guarantee _reconcile_interrupted_jobs gives for
+ a lost process, applied to a lost handler.
+ """
+ job.status = 'running'
+ job.started_at = job.started_at or datetime.utcnow()
+ db.session.commit()
+
+ stream = RunLogStream.for_job(job)
+ try:
+ result = handler(job) or {}
+ except Exception as exc:
+ logger.exception('Deployment kind %s raised', job.kind)
+ stream.log('error', f'{job.kind} failed: {exc}')
+ stream.flush()
+ db.session.rollback()
+ job.status = 'failed'
+ job.error_message = str(exc)
+ job.completed_at = datetime.utcnow()
+ db.session.commit()
+ return {'success': False, 'error': str(exc), 'job_id': job.id}
+
+ stream.flush()
+ # A handler may finalise the job itself; only fill in what it left.
+ if job.status not in ('succeeded', 'failed'):
+ job.status = 'succeeded' if result.get('success', True) else 'failed'
+ if not result.get('success', True):
+ job.error_message = result.get('error') or f'{job.kind} failed'
+ job.completed_at = datetime.utcnow()
+ db.session.commit()
+ # Handler extras first: the job's own status is the authoritative
+ # outcome and must not be overwritten by a handler that finalised the
+ # job one way and then returned the other.
+ return {**result, 'success': job.status == 'succeeded', 'job_id': job.id}
+
@staticmethod
def _run_demo_job(unified_job):
"""Unified-job handler for ``deploy.demo`` (same shape as
@@ -523,6 +655,7 @@ class DeploymentJobService:
registry.register(JOB_KIND, cls._run_install_job, replace=True)
registry.register(APP_JOB_KIND, cls._run_app_deploy_job, replace=True)
registry.register(DEMO_JOB_KIND, cls._run_demo_job, replace=True)
+ registry.register(REGISTERED_JOB_KIND, cls._run_registered_job, replace=True)
cls._reconcile_interrupted_jobs()
@classmethod
diff --git a/backend/tests/test_plugin_deploys_sdk.py b/backend/tests/test_plugin_deploys_sdk.py
new file mode 100644
index 00000000..87a883bd
--- /dev/null
+++ b/backend/tests/test_plugin_deploys_sdk.py
@@ -0,0 +1,150 @@
+"""Deployment kinds contributed by plugins (plugins_sdk.deploys).
+
+Covers the promise the SDK makes: a plugin's work becomes a real DeploymentJob,
+so it inherits the Deploy Console, the activity feed and retry without any
+frontend change — and a misbehaving handler can never leave a job stuck
+'running'.
+"""
+
+import pytest
+
+from app import db
+from app.models.deployment_job import DeploymentJob
+from app.services import deploy_kind_registry
+from app.services.deployment_job_service import DeploymentJobService
+
+
[email protected](autouse=True)
+def _clean_registry():
+ deploy_kind_registry.clear()
+ yield
+ deploy_kind_registry.clear()
+
+
+class TestRegistry:
+ def test_registers_and_resolves(self):
+ handler = lambda job: {'success': True}
+ deploy_kind_registry.register('demo.thing', handler)
+ assert deploy_kind_registry.get('demo.thing') is handler
+ assert 'demo.thing' in deploy_kind_registry.kinds()
+
+ def test_core_kinds_cannot_be_hijacked(self):
+ # A plugin overriding app_deploy would silently take over real
+ # deployments, so this is refused rather than merely discouraged.
+ for kind in ('app_deploy', 'template_install', 'demo_deploy'):
+ with pytest.raises(ValueError):
+ deploy_kind_registry.register(kind, lambda job: None)
+
+ def test_duplicate_registration_needs_replace(self):
+ deploy_kind_registry.register('demo.thing', lambda job: None)
+ with pytest.raises(ValueError):
+ deploy_kind_registry.register('demo.thing', lambda job: None)
+ deploy_kind_registry.register('demo.thing', lambda job: None, replace=True)
+
+ def test_rejects_non_callable(self):
+ with pytest.raises(ValueError):
+ deploy_kind_registry.register('demo.thing', 'not-callable')
+
+
+class TestRun:
+ def test_start_creates_a_job_addressable_by_the_console(self, app):
+ with app.app_context():
+ deploy_kind_registry.register('demo.thing', lambda job: {'success': True})
+ result = DeploymentJobService.start_registered(
+ 'demo.thing', steps=['One', 'Two'], wait=True,
+ )
+ assert result['success'] is True
+
+ job = DeploymentJob.query.get(result['job_id'])
+ assert job.kind == 'demo.thing'
+ assert job.status == 'succeeded'
+ # The step plan is what the console's pipeline strip and the feed's
+ # tick bar render from.
+ assert [s['name'] for s in job.get_plan()['steps']] == ['One', 'Two']
+ assert job.total_steps == 2
+
+ def test_start_refuses_an_unregistered_kind(self, app):
+ with app.app_context():
+ result = DeploymentJobService.start_registered('nobody.registered', wait=True)
+ assert result['success'] is False
+ assert 'no handler' in result['error'].lower()
+
+ def test_handler_returning_failure_marks_the_job_failed(self, app):
+ with app.app_context():
+ deploy_kind_registry.register(
+ 'demo.thing', lambda job: {'success': False, 'error': 'nope'})
+ result = DeploymentJobService.start_registered('demo.thing', wait=True)
+ assert result['success'] is False
+
+ job = DeploymentJob.query.get(result['job_id'])
+ assert job.status == 'failed'
+ assert job.error_message == 'nope'
+ assert job.completed_at is not None
+
+ def test_raising_handler_fails_the_job_instead_of_wedging_it(self, app):
+ # Third-party code: an exception must still end the job visibly, or the
+ # UI shows a deployment spinning forever with no explanation.
+ with app.app_context():
+ def boom(job):
+ raise RuntimeError('handler exploded')
+
+ deploy_kind_registry.register('demo.thing', boom)
+ result = DeploymentJobService.start_registered('demo.thing', wait=True)
+ assert result['success'] is False
+
+ job = DeploymentJob.query.get(result['job_id'])
+ assert job.status == 'failed'
+ assert 'handler exploded' in job.error_message
+ assert job.completed_at is not None
+
+ def test_handler_may_finalise_the_job_itself(self, app):
+ with app.app_context():
+ def finalise(job):
+ job.status = 'failed'
+ job.error_message = 'set by handler'
+ db.session.commit()
+ return {'success': True} # deliberately contradicts itself
+
+ deploy_kind_registry.register('demo.thing', finalise)
+ result = DeploymentJobService.start_registered('demo.thing', wait=True)
+
+ job = DeploymentJob.query.get(result['job_id'])
+ # A handler that took ownership of the outcome keeps it.
+ assert job.status == 'failed'
+ assert job.error_message == 'set by handler'
+ assert result['success'] is False
+
+
+class TestSdkFacade:
+ def test_sdk_exposes_register_start_and_kinds(self, app):
+ from app import plugins_sdk
+
+ with app.app_context():
+ plugins_sdk.deploys.register('demo.sdk', lambda job: {'success': True})
+ assert 'demo.sdk' in plugins_sdk.deploys.kinds()
+
+ result = plugins_sdk.deploys.start('demo.sdk', steps=['Only step'], wait=True)
+ assert result['success'] is True
+ assert DeploymentJob.query.get(result['job_id']).status == 'succeeded'
+
+ def test_steps_helper_advances_progress_and_records_the_failing_step(self, app):
+ from app import plugins_sdk
+
+ with app.app_context():
+ def two_steps(job):
+ with plugins_sdk.deploys.steps(job) as step:
+ with step('First'):
+ pass
+ with step('Second'):
+ raise RuntimeError('second failed')
+
+ plugins_sdk.deploys.register('demo.steps', two_steps)
+ result = plugins_sdk.deploys.start(
+ 'demo.steps', steps=['First', 'Second'], wait=True)
+
+ job = DeploymentJob.query.get(result['job_id'])
+ assert job.status == 'failed'
+ # Progress stopped on the step that failed — that is what the
+ # console highlights and the feed's tick bar shows in red.
+ assert job.current_step == 2
+ assert job.current_step_name == 'Second'