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 plugins own deployment-shaped work
Juan Denis6be60249f0c4
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 loggingimport osimport uuidfrom datetime import datetime@@ -9,7 +10,7 @@ from app import dbfrom app.models import Application, Serverfrom app.models.deployment_job import DeploymentJobfrom app.services.deployment_runner import DeploymentPlanRunner-from app.services.run_log_service import append_log+from app.services.run_log_service import append_log, RunLogStreamfrom app.services.docker_service import DockerServicefrom app.services.template_service import TemplateServicefrom app.services.telemetry_service import generate_correlation_id@@ -20,6 +21,9 @@ from app.services.telemetry_service import generate_correlation_idJOB_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 DemoDeployServicereturn 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_registryenqueue = {'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}+@staticmethoddef _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()@classmethoddiff --git a/backend/tests/test_plugin_deploys_sdk.py b/backend/tests/test_plugin_deploys_sdk.pynew file mode 100644index 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'