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(operations): adopt core run workflows

Juan Denis0cb26d6739da
diff --git a/backend/app/api/doctor.py b/backend/app/api/doctor.py
index 107ef07c..f534cc79 100644
--- a/backend/app/api/doctor.py
+++ b/backend/app/api/doctor.py
@@ -16,7 +16,7 @@ from flask import Blueprint, jsonify, request
from app.error_reporting import unexpected_response
from ..middleware.rbac import admin_required
-from ..services.doctor_service import DoctorService
+from ..services.doctor_service import DOCTOR_REPAIR_JOB_KIND, DoctorService
from ..services.drift_service import DRIFT_JOB_KIND, DriftService
doctor_bp = Blueprint('doctor', __name__)
@@ -94,12 +94,26 @@ def run_doctor():
@doctor_bp.route('/repair', methods=['POST'])
@admin_required
def repair_items():
- """Batch-repair the explicit items the operator selected."""
+ """Batch-repair selected items, optionally as a persisted operation.
+
+ Synchronous remains the default for existing CLI callers. The web shell
+ asks for ``wait=false`` and follows the returned job in Operations.
+ """
data = request.get_json(silent=True) or {}
items = data.get('items')
if not isinstance(items, list) or not items:
return jsonify({'error': "Body must carry a non-empty 'items' list."}), 400
try:
+ if request.args.get('wait', 'true').lower() == 'false':
+ from app.jobs.service import JobService
+ job = JobService.enqueue(
+ DOCTOR_REPAIR_JOB_KIND,
+ payload={'items': items},
+ max_attempts=1,
+ owner_type='doctor',
+ owner_id='host',
+ )
+ return jsonify({'job_id': job.id, 'kind': job.kind}), 202
return jsonify({'results': DoctorService.repair(items)})
except Exception as exc: # noqa: BLE001 - reported, not swallowed
return unexpected_response(exc)
diff --git a/backend/app/services/doctor_service.py b/backend/app/services/doctor_service.py
index 7f068dd2..64cffbc9 100644
--- a/backend/app/services/doctor_service.py
+++ b/backend/app/services/doctor_service.py
@@ -18,6 +18,7 @@ from datetime import datetime, timedelta
logger = logging.getLogger(__name__)
DOCTOR_JOB_KIND = 'doctor.run'
+DOCTOR_REPAIR_JOB_KIND = 'doctor.repair'
# Name of the built-in ScheduledJob row that runs the doctor sweep daily
# (seeded by app/jobs/builtin_handlers.py:seed_builtin_schedules).
DOCTOR_SCHEDULE_NAME = 'doctor'
@@ -954,9 +955,54 @@ class DoctorService:
return {'ran_at': report['ran_at'], 'counts': counts,
'dns_new_failures': new_failures}
+ @classmethod
+ def run_doctor_repair_job(cls, job):
+ """Run an explicit repair batch as a persisted shell operation."""
+ from app import db
+ from app.services.run_log_service import stream_for
+
+ items = (job.get_payload() or {}).get('items')
+ if not isinstance(items, list) or not items:
+ raise ValueError('doctor repair job requires a non-empty items list')
+
+ stream = stream_for(job)
+ stream.log('info', f'Starting {len(items)} doctor repair(s)')
+ results = cls.repair(items)
+ failed = []
+ for index, result in enumerate(results, start=1):
+ kind = ((result.get('item') or {}).get('kind') or 'repair')
+ if result.get('success'):
+ stream.log('info', f'{kind} repair succeeded', step_index=index)
+ else:
+ failed.append(result)
+ stream.log(
+ 'error',
+ f'{kind} repair failed: {result.get("error") or "unknown error"}',
+ step_index=index,
+ )
+ summary = {
+ 'results': results,
+ 'completed': len(results),
+ 'total': len(items),
+ 'failed': len(failed),
+ }
+ # Keep the item-level result when the consumer marks a partial failure
+ # terminal after this handler raises.
+ job.set_result(summary)
+ db.session.commit()
+ stream.flush()
+ if failed:
+ raise RuntimeError(
+ f'{len(failed)} of {len(items)} doctor repairs failed'
+ )
+ return summary
+
@classmethod
def register_jobs(cls):
"""Register the doctor handler with the job registry.
Called once at app startup (see app/__init__.py)."""
from app.jobs import registry
registry.register(DOCTOR_JOB_KIND, cls.run_doctor_job, replace=True)
+ registry.register(
+ DOCTOR_REPAIR_JOB_KIND, cls.run_doctor_repair_job, replace=True,
+ )
diff --git a/backend/tests/test_drift_doctor.py b/backend/tests/test_drift_doctor.py
index 3a0d436d..d027c75f 100644
--- a/backend/tests/test_drift_doctor.py
+++ b/backend/tests/test_drift_doctor.py
@@ -13,6 +13,7 @@ from app.services.drift_service import (
)
from app.services.doctor_service import (
DOCTOR_JOB_KIND,
+ DOCTOR_REPAIR_JOB_KIND,
DoctorService,
LAST_REPORT_KEY as DOCTOR_REPORT_KEY,
)
@@ -269,6 +270,7 @@ def test_register_jobs_registers_handlers(app):
DoctorService.register_jobs()
assert registry.get(DRIFT_JOB_KIND) is not None
assert registry.get(DOCTOR_JOB_KIND) is not None
+ assert registry.get(DOCTOR_REPAIR_JOB_KIND) is not None
# --------------------------------------------------------------------------- #
@@ -533,6 +535,55 @@ def test_post_repair_batch(doctor_client, auth_headers, monkeypatch):
{'item': items[1], 'success': True}]}
+def test_post_repair_can_enqueue_operation(doctor_client, auth_headers):
+ from app.jobs.models import Job
+
+ items = [{'kind': 'service', 'name': 'nginx'}]
+ resp = doctor_client.post(
+ '/api/v1/doctor/repair?wait=false',
+ headers=auth_headers,
+ json={'items': items},
+ )
+
+ assert resp.status_code == 202
+ body = resp.get_json()
+ assert body['kind'] == DOCTOR_REPAIR_JOB_KIND
+ job = Job.query.get(body['job_id'])
+ assert job.status == Job.STATUS_PENDING
+ assert job.get_payload() == {'items': items}
+ assert job.owner_type == 'doctor'
+ assert job.owner_id == 'host'
+
+
+def test_doctor_repair_job_persists_progress_and_fails_honestly(app, monkeypatch):
+ from app.jobs.models import Job
+ from app.jobs.service import JobService
+
+ items = [
+ {'kind': 'service', 'name': 'nginx'},
+ {'kind': 'dns', 'host': 'broken.example.com'},
+ ]
+ job = JobService.enqueue(
+ DOCTOR_REPAIR_JOB_KIND, {'items': items}, max_attempts=1,
+ )
+ monkeypatch.setattr(
+ DoctorService,
+ 'repair',
+ classmethod(lambda cls, selected: [
+ {'item': selected[0], 'success': True},
+ {'item': selected[1], 'success': False, 'error': 'still broken'},
+ ]),
+ )
+
+ with pytest.raises(RuntimeError, match='1 of 2 doctor repairs failed'):
+ DoctorService.run_doctor_repair_job(job)
+
+ persisted = Job.query.get(job.id).get_result()
+ assert persisted['completed'] == 2
+ assert persisted['total'] == 2
+ assert persisted['failed'] == 1
+
+
def test_post_repair_requires_items(doctor_client, auth_headers):
resp = doctor_client.post('/api/v1/doctor/repair', headers=auth_headers, json={})
assert resp.status_code == 400
diff --git a/frontend/src/components/backups/ProtectionPanel.jsx b/frontend/src/components/backups/ProtectionPanel.jsx
index 09405cbf..82669f80 100644
--- a/frontend/src/components/backups/ProtectionPanel.jsx
+++ b/frontend/src/components/backups/ProtectionPanel.jsx
@@ -8,6 +8,7 @@ import { History, RefreshCw, Loader2, List, CalendarDays, X } from 'lucide-react
import api from '@/services/api';
import { useToast } from '@/contexts/ToastContext';
+import { useOperations } from '@/contexts/OperationsContext';
import { useConfirm } from '@/hooks/useConfirm';
import { Button } from '@/components/ui/button';
@@ -32,6 +33,7 @@ export default function ProtectionPanel({ targetType, targetId, targetName, show
const toast = useToast();
const navigate = useNavigate();
const { confirm } = useConfirm();
+ const { openRun } = useOperations();
const [view, setView] = useState(null); // policy view payload
const [runs, setRuns] = useState([]);
@@ -129,7 +131,8 @@ export default function ProtectionPanel({ targetType, targetId, targetName, show
const handleBackupNow = useCallback(async () => {
setBackingUp(true);
try {
- await api.triggerBackup(targetType, targetId);
+ const result = await api.triggerBackup(targetType, targetId);
+ if (result?.job_id) openRun('job', result.job_id);
toast.success(t('app.protectionPanel.backupStarted', 'Backup started'));
scheduleReloads();
} catch (err) {
@@ -137,7 +140,7 @@ export default function ProtectionPanel({ targetType, targetId, targetName, show
} finally {
setBackingUp(false);
}
- }, [targetType, targetId, toast, scheduleReloads]);
+ }, [targetType, targetId, toast, scheduleReloads, openRun]);
const handleRunDrill = useCallback(async () => {
setDrilling(true);
diff --git a/frontend/src/components/monitoring/DoctorPanel.jsx b/frontend/src/components/monitoring/DoctorPanel.jsx
index 3d62b887..32c68039 100644
--- a/frontend/src/components/monitoring/DoctorPanel.jsx
+++ b/frontend/src/components/monitoring/DoctorPanel.jsx
@@ -9,6 +9,7 @@ import EmptyState from '../EmptyState';
import { ChevronDown, ChevronRight, Server, Stethoscope, Wrench } from 'lucide-react';
import { usePolling } from '@/hooks/usePolling';
import { useTranslation } from 'react-i18next';
+import { useOperations } from '@/contexts/OperationsContext';
// The fleet sweep fans out across agents over the network, so it is a job
@@ -64,6 +65,7 @@ const DoctorPanel = () => {
const { t } = useTranslation();
const toast = useToast();
const navigate = useNavigate();
+ const { openRun } = useOperations();
const [report, setReport] = useState(null);
const [loading, setLoading] = useState(true);
const [running, setRunning] = useState(false);
@@ -156,6 +158,14 @@ const DoctorPanel = () => {
const res = scope === 'fleet'
? await api.repairFleetItems(items)
: await api.repairDoctorItems(items);
+ if (scope !== 'fleet' && res.job_id) {
+ openRun('job', res.job_id);
+ toast.success(t(
+ 'app.doctorPanel.repairQueuedInOperations',
+ 'Repair queued — follow progress in Operations',
+ ));
+ return;
+ }
const results = res.results || [];
const failed = results.filter((r) => !r.success);
// Some repairs run as a background job rather than inline — a
diff --git a/frontend/src/components/security/ScannerTab.jsx b/frontend/src/components/security/ScannerTab.jsx
index a4ced76d..496c8686 100644
--- a/frontend/src/components/security/ScannerTab.jsx
+++ b/frontend/src/components/security/ScannerTab.jsx
@@ -15,6 +15,7 @@ import EmptyState from '@/components/EmptyState';
import { useConfirm } from '@/hooks/useConfirm';
import { usePolling } from '@/hooks/usePolling';
import { useTranslation } from 'react-i18next';
+import { useOperations } from '@/contexts/OperationsContext';
// Scan status cadence, and the faster cadence while a scan job runs.
const SCAN_STATUS_POLL_MS = 5000;
@@ -126,6 +127,7 @@ const HISTORY_VIEWS = [
const ScannerTab = () => {
const { t } = useTranslation();
const { confirm } = useConfirm();
+ const { openRun } = useOperations();
const [scanStatus, setScanStatus] = useState({ status: 'idle' });
const [scanPath, setScanPath] = useState('/var/www');
const [scanning, setScanning] = useState(false);
@@ -208,7 +210,8 @@ const ScannerTab = () => {
usePolling(async () => {
try {
- const job = await api.getJob(scanJobId);
+ const response = await api.getJob(scanJobId);
+ const job = response.job || response;
setScanJob(job);
if (!['succeeded', 'failed', 'cancelled'].includes(job.status)) return;
setScanJobId(null);
@@ -238,6 +241,7 @@ const ScannerTab = () => {
try {
const result = await api.scanApp(selectedApp);
setScanJob({ id: result.job_id, status: 'pending' });
+ openRun('job', result.job_id);
setMessage({ type: 'success', text: `Scan queued for ${result.path || 'app docroot'}` });
pollJob(result.job_id);
} catch (err) {
diff --git a/frontend/src/contexts/OperationsContext.jsx b/frontend/src/contexts/OperationsContext.jsx
index 20404454..13d95ab3 100644
--- a/frontend/src/contexts/OperationsContext.jsx
+++ b/frontend/src/contexts/OperationsContext.jsx
@@ -142,6 +142,19 @@ export function OperationsProvider({ children }) {
markRead(key);
}, [markRead]);
+ const openRun = useCallback((runKind, runId) => {
+ if (!runKind || runId == null) return;
+ if (runKind === 'job' && !canReadJobs) return;
+ const key = `${runKind}:${runId}`;
+ setLogSession(null);
+ setSelectedKey(key);
+ setCollapsed(false);
+ markRead(key);
+ // Creation responses carry only an id. Refresh immediately so the
+ // selected detail replaces its short loading state before the poll.
+ refresh();
+ }, [canReadJobs, markRead, refresh]);
+
const openLogSession = useCallback((session) => {
setSelectedKey(null);
setLogSession(session);
@@ -174,6 +187,7 @@ export function OperationsProvider({ children }) {
loading,
refresh,
openOperation,
+ openRun,
openLogSession,
closeLogSession,
selectOperation: setSelectedKey,
@@ -199,6 +213,7 @@ export function OperationsProvider({ children }) {
loading,
refresh,
openOperation,
+ openRun,
openLogSession,
closeLogSession,
markRead,
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index fad16434..166dfefc 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -1992,6 +1992,7 @@
"repairAll": "Repair all (",
"repairFailed": "{{length}} repair{{value}} failed — {{value2}}",
"repairFailed2": "Repair failed",
+ "repairQueuedInOperations": "Repair queued — follow progress in Operations",
"repairedItem": "Repaired {{length}} item{{value}}",
"runADiagnosisToCheckThis": "Run a diagnosis to check this server's managed configuration and core health.",
"serverDoctor": "Server Doctor",
diff --git a/frontend/src/pages/Jobs.jsx b/frontend/src/pages/Jobs.jsx
index 88a31cf2..74b638f3 100644
--- a/frontend/src/pages/Jobs.jsx
+++ b/frontend/src/pages/Jobs.jsx
@@ -151,9 +151,6 @@ function progressLabel(job) {
return '—';
}
-const isRunning = (s) => ['running', 'queued', 'pending', 'scheduled'].includes(String(s || '').toLowerCase());
-const canRetry = (s) => ['failed', 'error', 'cancelled', 'canceled'].includes(String(s || '').toLowerCase());
-
export default function Jobs() {
const { t } = useTranslation();
const { isAdmin } = useAuth();
@@ -338,12 +335,12 @@ export default function Jobs() {
cellClassName: 'sk-jobs__actions-cell',
render: (j) => (
<div className="sk-jobs__actions">
- {isRunning(j.status) && (
+ {j.can_cancel && (
<Button variant="ghost" size="sm" onClick={() => onCancel(j.id)}>
<XCircle size={14} /> {t('app.jobs.cancel', 'Cancel')}
</Button>
)}
- {canRetry(j.status) && (
+ {j.can_retry && (
<Button variant="ghost" size="sm" onClick={() => onRetry(j.id)}>
<RotateCcw size={14} /> {t('app.jobs.retry', 'Retry')}
</Button>
diff --git a/frontend/src/services/__tests__/operations.test.mjs b/frontend/src/services/__tests__/operations.test.mjs
index 5d957514..9e6fa50a 100644
--- a/frontend/src/services/__tests__/operations.test.mjs
+++ b/frontend/src/services/__tests__/operations.test.mjs
@@ -42,9 +42,28 @@ test('normalizes proof job kinds and keeps deploy queue mirrors out', () => {
const operations = normalizeOperations({
deployments: [{ id: 'dep-1', status: 'running' }],
- jobs: [{ id: 'mirror', kind: 'deploy.app', status: 'running' }, { id: 'job-1', kind: 'doctor.run' }],
+ jobs: [
+ { id: 'mirror', kind: 'deploy.app', status: 'running' },
+ { id: 'backup', kind: 'backup.policy.run', status: 'running' },
+ { id: 'doctor', kind: 'doctor.repair', status: 'running' },
+ { id: 'security', kind: 'security.malware_scan', status: 'running' },
+ ],
});
- assert.deepEqual(operations.map(operationKey).sort(), ['deploy:dep-1', 'job:job-1']);
+ assert.deepEqual(operations.map(operationKey).sort(), [
+ 'deploy:dep-1',
+ 'job:backup',
+ 'job:doctor',
+ 'job:security',
+ ]);
+ assert.deepEqual(
+ Object.fromEntries(operations.map((operation) => [operation.id, operation.title])),
+ {
+ 'dep-1': 'Application deployment',
+ backup: 'Backup policy run',
+ doctor: 'Doctor repair',
+ security: 'Security scan',
+ },
+ );
});
test('bounds terminal history without dropping active or selected work', () => {
diff --git a/frontend/src/services/api/doctor.js b/frontend/src/services/api/doctor.js
index 39a92e5c..66d6c3ae 100644
--- a/frontend/src/services/api/doctor.js
+++ b/frontend/src/services/api/doctor.js
@@ -10,7 +10,7 @@ export async function runDoctor() {
}
export async function repairDoctorItems(items) {
- return this.request('/doctor/repair', {
+ return this.request('/doctor/repair?wait=false', {
method: 'POST',
body: JSON.stringify({ items }),
});
diff --git a/frontend/src/services/operations.js b/frontend/src/services/operations.js
index 691a6a70..b1be537e 100644
--- a/frontend/src/services/operations.js
+++ b/frontend/src/services/operations.js
@@ -39,6 +39,7 @@ function normalizeProgress(source) {
function jobTitle(job) {
if (job.kind === 'backup.policy.run') return 'Backup policy run';
+ if (job.kind === 'doctor.repair') return 'Doctor repair';
if (job.kind === 'doctor.run' || job.kind === 'doctor.fleet.run') return 'Server doctor';
if (SECURITY_KIND.test(job.kind || '')) return 'Security scan';
return (job.kind || 'Background job').replaceAll('.', ' ');