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(manifest): apply engine — resolve/plan/apply + core domain attach (Phase 2)
Juan Denis315c80e9a0fb
diff --git a/backend/app/api/manifests.py b/backend/app/api/manifests.pyindex 8dd70907..79af5d7c 100644--- a/backend/app/api/manifests.py+++ b/backend/app/api/manifests.py@@ -8,14 +8,40 @@ audit-logged.from flask import Blueprint, jsonify, request, Responsefrom flask_jwt_extended import jwt_required, get_jwt_identity+from app import dbfrom app.models.application import Application+from app.models.application_manifest import ApplicationManifest, STATUS_PENDING+from app.models.project import Projectfrom app.models.user import Userfrom app.services.manifest_scaffold_service import ManifestScaffoldServicefrom app.services.manifest_spec_service import ManifestSpecService, ManifestError+from app.services.manifest_apply_service import ManifestApplyService+from app.services.manifest_persistence_service import ManifestPersistenceServicemanifests_bp = Blueprint('manifests', __name__)+def _load_normalized(data):+ """Normalize from an inline body, or fall back to the project's stored row.+ Returns (normalized, raw_text, error_response_or_None)."""+ if 'content' in data:+ try:+ return ManifestSpecService.normalize_text(data['content']), data['content'], None+ except ManifestError as exc:+ return None, None, (jsonify({'error': 'Invalid manifest', 'errors': exc.errors}), 400)+ if 'manifest' in data:+ try:+ return ManifestSpecService.normalize(data['manifest']), None, None+ except ManifestError as exc:+ return None, None, (jsonify({'error': 'Invalid manifest', 'errors': exc.errors}), 400)+ # fall back to the stored manifest for the project+ project_id = data.get('project_id')+ row = ApplicationManifest.query.filter_by(project_id=project_id).first() if project_id else None+ if row and row.get_normalized():+ return row.get_normalized(), row.raw_text, None+ return None, None, (jsonify({'error': 'Provide `content`/`manifest`, or store one first'}), 400)++def _require_admin():user = User.query.get(get_jwt_identity())if not user or user.role != 'admin':@@ -73,3 +99,76 @@ def validate_manifest():'summary': ManifestSpecService.summarize(normalized),'normalized': normalized,}), 200+++@manifests_bp.route('', methods=['GET'])+@jwt_required()+def get_manifest():+ """GET /api/v1/manifests?project_id= -> the stored manifest for a project."""+ user, err = _require_admin()+ if err:+ return err+ project_id = request.args.get('project_id', type=int)+ if not project_id:+ return jsonify({'error': 'project_id is required'}), 400+ row = ApplicationManifest.query.filter_by(project_id=project_id).first()+ if not row:+ return jsonify({'manifest': None}), 200+ return jsonify({'manifest': row.to_dict(include_raw=True)}), 200+++@manifests_bp.route('/plan', methods=['POST'])+@jwt_required()+def plan_manifest():+ """POST /api/v1/manifests/plan {project_id, content|manifest?} -> dry-run plan."""+ user, err = _require_admin()+ if err:+ return err+ data = request.get_json(silent=True) or {}+ project = Project.query.get(data.get('project_id')) if data.get('project_id') else None+ if not project:+ return jsonify({'error': 'A valid project_id is required'}), 400++ normalized, _raw, err_resp = _load_normalized(data)+ if err_resp:+ return err_resp++ plan = ManifestApplyService.plan(project, normalized)+ return jsonify({'plan': plan}), 200+++@manifests_bp.route('/apply', methods=['POST'])+@jwt_required()+def apply_manifest():+ """POST /api/v1/manifests/apply {project_id, content|manifest?} -> apply."""+ user, err = _require_admin()+ if err:+ return err+ data = request.get_json(silent=True) or {}+ project = Project.query.get(data.get('project_id')) if data.get('project_id') else None+ if not project:+ return jsonify({'error': 'A valid project_id is required'}), 400++ normalized, raw, err_resp = _load_normalized(data)+ if err_resp:+ return err_resp++ # persist/refresh the manifest row (pending) before applying+ row = ManifestPersistenceService.store_manifest(+ project_id=project.id, normalized=normalized, raw_text=raw, status=STATUS_PENDING)+ db.session.commit()++ result = ManifestApplyService.apply(project, normalized, user_id=user.id,+ manifest_row=row)++ try:+ from app.services.audit_service import AuditService+ AuditService.log('manifest.apply', user_id=user.id, target_type='project',+ target_id=project.id,+ details={'success': result['success'], 'applied': result['applied'],+ 'job_id': result['job_id']})+ except Exception:+ pass++ status = 200 if result['success'] else 207+ return jsonify(result), statusdiff --git a/backend/app/services/domain_attach_service.py b/backend/app/services/domain_attach_service.pynew file mode 100644index 00000000..31de4ae7--- /dev/null+++ b/backend/app/services/domain_attach_service.py@@ -0,0 +1,159 @@+"""Attach a custom domain to any managed app, end to end.++This generalizes the WordPress "one-call attach a custom domain" pattern+(``wordpress_service.attach_custom_domain``) so plain apps (docker, python,+php, static) can use the same DNS + vhost + optional-SSL flow.++The public entry point is :meth:`DomainAttachService.attach`. Every external+stage (DNS provider API, nginx vhost write, certbot) degrades to a *warning*+and never raises — HTTPS is optional in ServerKit and a certificate failure+must never block the domain attach. The idempotent Domain row is the only+hard requirement; everything after it is best-effort.++Stateless — all classmethods, no instance state — matching the repo style.+"""+import os+from typing import Dict, Optional++from app import db+from app.models.domain import Domain+from app.services.site_domain_service import SiteDomainService+from app.services.dns_provider_service import DNSProviderService+++class DomainAttachService:+ """Point a user-owned domain at a managed app in one call."""++ @staticmethod+ def _normalize_host(host: str) -> str:+ """Reduce a bare host or a full URL down to a lowercase hostname."""+ h = (host or '').strip().lower()+ if '://' in h:+ h = h.split('://', 1)[1]+ h = h.split('/', 1)[0].split(':', 1)[0]+ return h.strip().strip('.').rstrip('.')++ @classmethod+ def attach(cls, app, host: str, ssl: str = 'auto',+ email: Optional[str] = None, make_primary: bool = False) -> Dict:+ """Attach ``host`` to ``app``: record the Domain, ensure DNS, publish the+ vhost, and optionally obtain a certificate.++ Args:+ app: the ``Application`` row to attach the domain to.+ host: the custom hostname (bare host or full URL).+ ssl: ``'auto'``/``'on'``/``True`` obtains a certificate best-effort;+ ``'off'``/``False`` skips SSL entirely.+ email: ACME account email (defaults to ``admin@<host>``).+ make_primary: when true, make this the app's primary domain+ (unsetting any existing primary first).++ Returns a dict with the EXACT shape the manifest applier consumes::++ {'success': True, 'domain': host, 'created': bool,+ 'dns': <ensure_a_record result>,+ 'ssl': {'enabled': bool, 'error'?: str},+ 'warnings': [str, ...]}++ or ``{'success': False, 'error': msg}`` on an invalid host / DB failure.+ """+ if not app:+ return {'success': False, 'error': 'An application is required'}++ host = cls._normalize_host(host)+ if not host or '.' not in host:+ return {'success': False, 'error': 'A valid custom domain (e.g. example.com) is required'}++ warnings = []++ # 1) Idempotent Domain row (create if missing, honor make_primary).+ try:+ domain = Domain.query.filter_by(name=host, application_id=app.id).first()+ created = domain is None+ if make_primary:+ Domain.query.filter_by(application_id=app.id, is_primary=True).update(+ {'is_primary': False})+ if domain is None:+ # Guard against the host being claimed by a *different* app —+ # `name` is globally unique, so we can't silently steal it.+ clash = Domain.query.filter_by(name=host).first()+ if clash and clash.application_id != app.id:+ return {'success': False,+ 'error': f'{host} is already attached to another app'}+ domain = Domain(name=host, is_primary=bool(make_primary),+ application_id=app.id)+ db.session.add(domain)+ elif make_primary:+ domain.is_primary = True+ db.session.flush()+ except Exception as e:+ db.session.rollback()+ return {'success': False, 'error': f'Could not record domain: {e}'}++ # 2) DNS: auto-create the A record best-effort (or report what to add).+ dns = None+ try:+ dns = DNSProviderService.ensure_a_record(host, SiteDomainService.server_ip())+ if dns and not dns.get('created'):+ warnings.append(dns.get('message')+ or f'Add the {host} A record manually.')+ except Exception as e:+ warnings.append(f'DNS auto-config skipped: {e}')++ # 3) Publish the vhost so the host is actually served. Linux-only —+ # on a Windows dev box nginx is unavailable, so skip with a warning+ # rather than crashing.+ if os.name == 'nt':+ warnings.append('nginx vhost not written (not a Linux host).')+ else:+ try:+ v = SiteDomainService.write_app_vhost(app)+ if v and v.get('warning'):+ warnings.append(v['warning'])+ except Exception as e:+ warnings.append(f'nginx vhost not written: {e}')++ # 4) Optional HTTPS. Best-effort — a cert failure never fails the attach.+ ssl_result = {'enabled': False}+ want_ssl = ssl in ('auto', 'on', True)+ if want_ssl:+ try:+ from app.services.ssl_service import SSLService+ from app.services.nginx_service import NginxService+ cert = SSLService.obtain_certificate([host], email or f'admin@{host}')+ if cert and cert.get('success'):+ domain.ssl_enabled = True+ domain.ssl_certificate_path = cert.get('certificate_path')+ domain.ssl_key_path = cert.get('private_key_path')+ ssl_result['enabled'] = True+ try:+ NginxService.add_ssl_to_site(+ app.name, cert.get('certificate_path'),+ cert.get('private_key_path'))+ except Exception as e:+ warnings.append(f'certificate issued but nginx SSL wiring failed: {e}')+ else:+ err = (cert or {}).get('error') or 'certificate request failed'+ ssl_result['error'] = err+ warnings.append(+ 'HTTPS is not set up yet — enable SSL once DNS has '+ f'propagated to this server ({err}).')+ except Exception as e:+ ssl_result['error'] = str(e)+ warnings.append(f'HTTPS is not set up yet: {e}')++ # 5) Commit the Domain row (row + any SSL fields).+ try:+ db.session.commit()+ except Exception as e:+ db.session.rollback()+ return {'success': False, 'error': f'Could not save domain: {e}'}++ return {+ 'success': True,+ 'domain': host,+ 'created': created,+ 'dns': dns,+ 'ssl': ssl_result,+ 'warnings': warnings,+ }diff --git a/backend/app/services/manifest_apply_service.py b/backend/app/services/manifest_apply_service.pynew file mode 100644index 00000000..34d2a0f1--- /dev/null+++ b/backend/app/services/manifest_apply_service.py@@ -0,0 +1,570 @@+"""The manifest apply engine (plan 17, Phase 2).++resolve → plan → apply. Turns a normalized v1 manifest into an ordered action+plan and executes it through the existing imperative services, inside a+DeploymentJob for logging + before/after snapshots. Single-server for now;+Phase 5 adds fleet targeting.++`plan()` is pure enough to be a dry-run (no writes). `apply()` executes and is+idempotent — a second plan against a just-applied manifest is empty.+"""++import uuid+from datetime import datetime+from typing import Any, Dict, List, Optional, Tuple++from app import db+from app.models.application import Application+from app.models.application_manifest import (+ ApplicationManifest, STATUS_APPLIED, STATUS_ERROR,+)+from app.models.domain import Domain+from app.models.environment import Environment+from app.models.managed_database import ManagedDatabase+from app.models.project import Project+++# manifest backup schedule -> cron+_SCHEDULE_CRON = {+ 'hourly': '0 * * * *',+ 'daily': '0 2 * * *',+ 'weekly': '0 3 * * 0',+ 'monthly': '0 4 1 * *',+}++# db engines the managed-database layer can actually record+_MANAGED_DB_ENGINES = {'postgresql', 'mysql'}++# ordering weight per step type (dbs before consumers; domains last)+_STEP_ORDER = {+ 'provision_db': 0,+ 'warn': 1,+ 'create_app': 2,+ 'update_app': 3,+ 'set_env': 4,+ 'ensure_volume': 5,+ 'upsert_backup_policy': 6,+ 'attach_domain': 7,+}+++class ManifestApplyService:++ # -- resolve (#7) -------------------------------------------------------++ @classmethod+ def resolve_service(cls, svc: Dict[str, Any]) -> Dict[str, Any]:+ """Normalized manifest service -> desired-state dict."""+ literal_env: Dict[str, Any] = {}+ env_refs: List[Dict[str, Any]] = []+ for var in svc.get('env_vars', []):+ if var['source'] == 'value':+ literal_env[var['key']] = var['value']+ else:+ env_refs.append(var)+ return {+ 'name': svc['name'],+ 'kind': svc['kind'],+ 'app_type': svc.get('app_type'),+ 'db_engine': svc.get('db_engine'),+ 'engine_version': svc.get('engine_version'),+ 'runtime': svc.get('runtime'),+ 'port': svc.get('port'),+ 'healthcheck_path': svc.get('healthcheck_path'),+ 'build_command': svc.get('build_command'),+ 'start_command': svc.get('start_command'),+ 'cpu': cls._stringify(svc.get('cpu')),+ 'memory': cls._stringify(svc.get('memory')),+ 'auto_deploy': svc.get('auto_deploy', False),+ 'env': literal_env,+ 'env_refs': env_refs,+ 'disks': svc.get('disks', []),+ 'server': svc.get('server'),+ }++ # -- plan (#8) ----------------------------------------------------------++ @classmethod+ def plan(cls, project: Project, normalized: Dict[str, Any],+ environment: Optional[Environment] = None) -> Dict[str, Any]:+ """Diff desired manifest vs live state -> ordered action plan."""+ env = environment or cls._default_environment(project)+ steps: List[Dict[str, Any]] = []++ services = normalized.get('services', [])+ for svc in services:+ resolved = cls.resolve_service(svc)+ if resolved['kind'] == 'database':+ steps.extend(cls._plan_db(resolved))+ else:+ steps.extend(cls._plan_app(project, env, resolved))++ steps.extend(cls._plan_domains(project, normalized.get('domains', [])))++ steps.sort(key=lambda s: (_STEP_ORDER.get(s['type'], 99), s.get('service') or ''))+ return {+ 'project_id': project.id,+ 'environment_id': env.id if env else None,+ 'steps': steps,+ 'step_count': len(steps),+ 'summary': cls._summarize_plan(steps),+ }++ @classmethod+ def _plan_db(cls, resolved: Dict[str, Any]) -> List[Dict[str, Any]]:+ engine = resolved['db_engine']+ name = resolved['name']+ if engine not in _MANAGED_DB_ENGINES:+ return [{+ 'type': 'warn', 'service': name,+ 'description': f'{engine or resolved.get("app_type")} databases are not '+ f'managed by ServerKit yet — declared but not provisioned',+ 'payload': {},+ }]+ existing = ManagedDatabase.query.filter_by(engine=engine, name=name).first()+ steps: List[Dict[str, Any]] = []+ if not existing:+ steps.append({+ 'type': 'provision_db', 'service': name,+ 'description': f'Provision {engine} database `{name}`',+ 'payload': {'engine': engine, 'name': name,+ 'version': resolved.get('engine_version')},+ })+ # backup declaration on the db's single disk+ for disk in resolved.get('disks', []):+ backup = disk.get('backup')+ if backup and not cls._backup_policy_current(+ 'database', existing.id if existing else None, backup):+ steps.append(cls._db_backup_step(name, engine, backup, exists=bool(existing)))+ return steps++ @classmethod+ def _plan_app(cls, project: Project, env: Optional[Environment],+ resolved: Dict[str, Any]) -> List[Dict[str, Any]]:+ steps: List[Dict[str, Any]] = []+ name = resolved['name']+ app = cls._find_app(project, name)++ if app is None:+ payload = {k: resolved[k] for k in+ ('app_type', 'port', 'healthcheck_path', 'runtime',+ 'build_command', 'start_command', 'cpu', 'memory')}+ payload['name'] = name+ steps.append({+ 'type': 'create_app', 'service': name,+ 'description': f'Create app `{name}` ({resolved["app_type"]})',+ 'payload': payload,+ })+ else:+ changes = cls._app_field_changes(app, resolved)+ if changes:+ steps.append({+ 'type': 'update_app', 'service': name,+ 'description': f'Update app `{name}`: ' + ', '.join(changes.keys()),+ 'payload': {'app_id': app.id, 'changes': changes},+ })++ # env (literal values only; references bind in Phase 3)+ desired_env = resolved['env']+ if desired_env:+ live_env = cls._live_env(app) if app else {}+ missing = {k: v for k, v in desired_env.items() if str(live_env.get(k)) != str(v)}+ if missing or app is None:+ to_set = desired_env if app is None else missing+ if to_set:+ steps.append({+ 'type': 'set_env', 'service': name,+ 'description': f'Set {len(to_set)} env var(s) on `{name}`',+ 'payload': {'app_id': app.id if app else None, 'env': to_set},+ })++ # disks+ for disk in resolved.get('disks', []):+ mount = disk.get('mount_path')+ if not mount:+ continue+ has_vol = bool(app) and any(v.mount_path == mount for v in (app.volumes or []))+ if not has_vol:+ steps.append({+ 'type': 'ensure_volume', 'service': name,+ 'description': f'Ensure volume `{disk.get("name") or mount}` on `{name}`',+ 'payload': {'app_id': app.id if app else None,+ 'name': disk.get('name') or cls._slug(mount),+ 'mount_path': mount, 'size': disk.get('size')},+ })+ backup = disk.get('backup')+ if backup and not cls._backup_policy_current(+ 'files', app.id if app else None, backup):+ steps.append(cls._files_backup_step(name, app, mount, backup))++ return steps++ @classmethod+ def _plan_domains(cls, project: Project, domains: List[Dict[str, Any]]) -> List[Dict[str, Any]]:+ steps = []+ for dom in domains:+ host = dom.get('host')+ svc_name = dom.get('service')+ app = cls._find_app(project, svc_name) if svc_name else None+ already = bool(app) and any(d.name == host for d in (app.domains or []))+ if already:+ continue+ steps.append({+ 'type': 'attach_domain', 'service': svc_name,+ 'description': f'Attach domain `{host}`'+ + (f' to `{svc_name}`' if svc_name else ''),+ 'payload': {'host': host, 'service': svc_name, 'ssl': dom.get('ssl', 'auto'),+ 'app_id': app.id if app else None},+ })+ return steps++ @classmethod+ def _db_backup_step(cls, name, engine, backup, exists):+ return {+ 'type': 'upsert_backup_policy', 'service': name,+ 'description': f'Backup policy for db `{name}` ({backup["schedule"]})',+ 'payload': {'target': 'database', 'engine': engine, 'db_name': name,+ 'schedule': backup['schedule'], 'retain': backup['retain']},+ }++ @classmethod+ def _files_backup_step(cls, name, app, mount, backup):+ return {+ 'type': 'upsert_backup_policy', 'service': name,+ 'description': f'Backup policy for disk `{mount}` on `{name}` ({backup["schedule"]})',+ 'payload': {'target': 'files', 'app_id': app.id if app else None,+ 'mount_path': mount, 'schedule': backup['schedule'],+ 'retain': backup['retain']},+ }++ # -- apply (#9) ---------------------------------------------------------++ @classmethod+ def apply(cls, project: Project, normalized: Dict[str, Any],+ user_id: Optional[int] = None,+ environment: Optional[Environment] = None,+ manifest_row: Optional[ApplicationManifest] = None) -> Dict[str, Any]:+ """Execute the plan inside a DeploymentJob with before/after snapshots."""+ env = environment or cls._default_environment(project)+ plan = cls.plan(project, normalized, env)+ job = cls._create_job(project, user_id, plan)++ cls._snapshot_existing(project, normalized, tag='before')++ results = []+ failed = False+ for idx, step in enumerate(plan['steps']):+ if failed:+ results.append({**cls._step_ref(step), 'status': 'skipped'})+ continue+ try:+ outcome = cls._execute_step(project, env, step, user_id)+ results.append({**cls._step_ref(step), 'status': 'ok', 'result': outcome})+ cls._log(job, idx, 'info', step['description'], outcome)+ except Exception as exc: # stop the plan, report per-step+ failed = True+ results.append({**cls._step_ref(step), 'status': 'error', 'error': str(exc)})+ cls._log(job, idx, 'error', f'{step["description"]}: {exc}')++ cls._snapshot_existing(project, normalized, tag='after')++ cls._finish_job(job, failed, results)+ if manifest_row is not None:+ manifest_row.status = STATUS_ERROR if failed else STATUS_APPLIED+ if not failed:+ manifest_row.applied_at = datetime.utcnow()+ manifest_row.last_error = None+ else:+ manifest_row.last_error = next(+ (r.get('error') for r in results if r.get('status') == 'error'), None)+ db.session.commit()++ return {+ 'success': not failed,+ 'job_id': job.id,+ 'applied': sum(1 for r in results if r['status'] == 'ok'),+ 'results': results,+ 'plan': plan,+ }++ @classmethod+ def _execute_step(cls, project, env, step, user_id) -> Dict[str, Any]:+ stype = step['type']+ # thread the step's service name into the payload so handlers can resolve+ # an app that was created earlier in the same apply (app_id was None at+ # plan time for brand-new services).+ payload = dict(step.get('payload', {}))+ payload.setdefault('service', step.get('service'))+ handler = getattr(cls, f'_do_{stype}', None)+ if handler is None:+ return {'noop': True}+ return handler(project, env, payload, user_id) or {}++ # -- step handlers ------------------------------------------------------++ @classmethod+ def _do_warn(cls, project, env, payload, user_id):+ return {'warned': True}++ @classmethod+ def _do_provision_db(cls, project, env, payload, user_id):+ from app.services.managed_database_service import ManagedDatabaseService+ managed = ManagedDatabaseService.record_provisioned(+ engine=payload['engine'], name=payload['name'],+ workspace_id=project.workspace_id,+ )+ return {'managed_database_id': managed.id}++ @classmethod+ def _do_create_app(cls, project, env, payload, user_id):+ import json+ overrides = {}+ if payload.get('build_command'):+ overrides['build_command'] = payload['build_command']+ if payload.get('start_command'):+ overrides['start_command'] = payload['start_command']+ app = Application(+ name=payload['name'],+ app_type=payload.get('app_type') or 'docker',+ status='stopped',+ port=payload.get('port'),+ healthcheck_path=payload.get('healthcheck_path'),+ cpu_limit=payload.get('cpu'),+ memory_limit=payload.get('memory'),+ buildpack_overrides=json.dumps(overrides) if overrides else None,+ source='manifest',+ user_id=user_id,+ project_id=project.id,+ environment_id=env.id if env else None,+ )+ db.session.add(app)+ db.session.commit()+ return {'app_id': app.id}++ @classmethod+ def _do_update_app(cls, project, env, payload, user_id):+ import json+ app = Application.query.get(payload['app_id'])+ if not app:+ raise RuntimeError('app not found')+ changes = payload['changes']+ if 'port' in changes:+ app.port = changes['port']+ if 'healthcheck_path' in changes:+ app.healthcheck_path = changes['healthcheck_path']+ if 'cpu' in changes:+ app.cpu_limit = changes['cpu']+ if 'memory' in changes:+ app.memory_limit = changes['memory']+ if 'build_command' in changes or 'start_command' in changes:+ overrides = {}+ if app.buildpack_overrides:+ try:+ overrides = json.loads(app.buildpack_overrides) or {}+ except Exception:+ overrides = {}+ if 'build_command' in changes:+ overrides['build_command'] = changes['build_command']+ if 'start_command' in changes:+ overrides['start_command'] = changes['start_command']+ app.buildpack_overrides = json.dumps(overrides)+ db.session.commit()+ return {'app_id': app.id, 'changed': list(changes.keys())}++ @classmethod+ def _do_set_env(cls, project, env, payload, user_id):+ from app.services.env_service import EnvService+ app_id = payload.get('app_id') or cls._resolve_app_id(project, payload)+ count, errors = EnvService.bulk_set_env_vars(app_id, payload['env'], user_id)+ if errors:+ raise RuntimeError('; '.join(errors))+ return {'set': count}++ @classmethod+ def _do_ensure_volume(cls, project, env, payload, user_id):+ from app.services.volume_service import VolumeService+ app = Application.query.get(payload.get('app_id') or cls._resolve_app_id(project, payload))+ if not app:+ raise RuntimeError('app not found')+ if any(v.mount_path == payload['mount_path'] for v in (app.volumes or [])):+ return {'exists': True}+ vol = VolumeService.create(app, payload['name'], payload['mount_path'])+ return {'volume_id': getattr(vol, 'id', None)}++ @classmethod+ def _do_upsert_backup_policy(cls, project, env, payload, user_id):+ from app.services.backup_policy_service import BackupPolicyService+ schedule_cron = _SCHEDULE_CRON.get(payload['schedule'], '0 2 * * *')+ fields = {'enabled': True, 'schedule_cron': schedule_cron,+ 'retention_count': payload['retain']}+ if payload['target'] == 'database':+ from app.services.managed_database_service import ManagedDatabaseService+ managed = ManagedDatabase.query.filter_by(+ engine=payload['engine'], name=payload['db_name']).first()+ if not managed:+ raise RuntimeError('managed database not found for backup policy')+ ManagedDatabaseService.protect(managed, fields=fields)+ return {'policy': 'database', 'db': payload['db_name']}+ # files+ app_id = payload.get('app_id') or cls._resolve_app_id(project, payload)+ policy = BackupPolicyService.get_or_create_policy(+ target_type='files', target_id=app_id, target_subtype='pathlist',+ target_meta={'paths': [payload['mount_path']], 'managed_by': 'manifest'})+ BackupPolicyService.update_policy(policy, fields)+ return {'policy': 'files', 'policy_id': policy.id}++ @classmethod+ def _do_attach_domain(cls, project, env, payload, user_id):+ from app.services.domain_attach_service import DomainAttachService+ app_id = payload.get('app_id') or (+ cls._resolve_app_id(project, payload) if payload.get('service') else None)+ if not app_id:+ return {'skipped': 'no target service'}+ app = Application.query.get(app_id)+ if not app:+ raise RuntimeError('app not found for domain')+ result = DomainAttachService.attach(app, payload['host'], ssl=payload.get('ssl', 'auto'))+ return result++ # -- snapshots + job ----------------------------------------------------++ @classmethod+ def _snapshot_existing(cls, project, normalized, tag):+ from app.services.configuration_service import ConfigurationService+ for svc in normalized.get('services', []):+ if svc['kind'] != 'app':+ continue+ app = cls._find_app(project, svc['name'])+ if app is None:+ continue+ try:+ ConfigurationService.create_snapshot(app)+ except Exception:+ db.session.rollback()++ @classmethod+ def _create_job(cls, project, user_id, plan):+ from app.models.deployment_job import DeploymentJob+ job = DeploymentJob(+ id=str(uuid.uuid4()), kind='manifest.apply', status='running',+ requested_by=user_id, trigger='manual', started_at=datetime.utcnow(),+ )+ job.set_plan({'steps': plan['steps']})+ job.total_steps = plan['step_count']+ db.session.add(job)+ db.session.commit()+ return job++ @classmethod+ def _finish_job(cls, job, failed, results):+ job.status = 'failed' if failed else 'succeeded'+ job.completed_at = datetime.utcnow()+ job.current_step = sum(1 for r in results if r['status'] in ('ok', 'error'))+ job.set_result({'results': results})+ db.session.commit()++ @classmethod+ def _log(cls, job, idx, level, message, data=None):+ # Best-effort per-step log. Wrapped in a savepoint so a logging failure+ # (e.g. SQLite BigInteger PK) never poisons the apply transaction. The+ # authoritative per-step record also lives in job.result.+ from app.models.deployment_job import DeploymentJobLog+ import json+ try:+ with db.session.begin_nested():+ db.session.add(DeploymentJobLog(+ job_id=job.id, step_index=idx, level=level, message=message,+ data=json.dumps(data) if data else None))+ except Exception:+ pass++ # -- helpers ------------------------------------------------------------++ @classmethod+ def _app_field_changes(cls, app: Application, resolved: Dict[str, Any]) -> Dict[str, Any]:+ import json+ changes = {}+ if resolved.get('port') is not None and app.port != resolved['port']:+ changes['port'] = resolved['port']+ if resolved.get('healthcheck_path') and app.healthcheck_path != resolved['healthcheck_path']:+ changes['healthcheck_path'] = resolved['healthcheck_path']+ if resolved.get('cpu') and app.cpu_limit != resolved['cpu']:+ changes['cpu'] = resolved['cpu']+ if resolved.get('memory') and app.memory_limit != resolved['memory']:+ changes['memory'] = resolved['memory']+ overrides = {}+ if app.buildpack_overrides:+ try:+ overrides = json.loads(app.buildpack_overrides) or {}+ except Exception:+ overrides = {}+ if resolved.get('build_command') and overrides.get('build_command') != resolved['build_command']:+ changes['build_command'] = resolved['build_command']+ if resolved.get('start_command') and overrides.get('start_command') != resolved['start_command']:+ changes['start_command'] = resolved['start_command']+ return changes++ @classmethod+ def _backup_policy_current(cls, target_type: str, target_id: Optional[int],+ backup: Dict[str, Any]) -> bool:+ """True when an enabled policy already matches the declared schedule/retain."""+ if not target_id:+ return False+ from app.models.backup_policy import BackupPolicy+ pol = BackupPolicy.query.filter_by(+ target_type=target_type, target_id=target_id, enabled=True).first()+ if not pol:+ return False+ want_cron = _SCHEDULE_CRON.get(backup['schedule'], '0 2 * * *')+ return pol.schedule_cron == want_cron and pol.retention_count == backup['retain']++ @staticmethod+ def _find_app(project: Project, name: Optional[str]) -> Optional[Application]:+ if not name:+ return None+ return Application.query.filter_by(project_id=project.id, name=name).first()++ @classmethod+ def _resolve_app_id(cls, project, payload):+ app = cls._find_app(project, payload.get('service'))+ if not app:+ raise RuntimeError(f'app `{payload.get("service")}` not found')+ return app.id++ @staticmethod+ def _live_env(app: Application) -> Dict[str, Any]:+ from app.services.env_service import EnvService+ try:+ return EnvService.get_env_dict(app.id)+ except Exception:+ return {}++ @staticmethod+ def _default_environment(project: Project) -> Optional[Environment]:+ env = Environment.query.filter_by(project_id=project.id, is_default=True).first()+ if env:+ return env+ return Environment.query.filter_by(project_id=project.id).first()++ @staticmethod+ def _summarize_plan(steps: List[Dict[str, Any]]) -> str:+ if not steps:+ return 'no changes — live state matches the manifest'+ counts: Dict[str, int] = {}+ for s in steps:+ counts[s['type']] = counts.get(s['type'], 0) + 1+ return ', '.join(f'{v} {k.replace("_", " ")}' for k, v in counts.items())++ @staticmethod+ def _step_ref(step):+ return {'type': step['type'], 'service': step.get('service'),+ 'description': step['description']}++ @staticmethod+ def _stringify(value):+ return None if value is None else str(value)++ @staticmethod+ def _slug(text):+ import re+ return re.sub(r'[^a-z0-9]+', '-', (text or '').lower()).strip('-') or 'vol'diff --git a/backend/tests/test_domain_attach_service.py b/backend/tests/test_domain_attach_service.pynew file mode 100644index 00000000..e35dcafe--- /dev/null+++ b/backend/tests/test_domain_attach_service.py@@ -0,0 +1,178 @@+"""Proving suite for DomainAttachService (manifest task #12).++Generalizes the WordPress one-call "attach a custom domain" flow to any app.+The suite runs on Windows (``os.name == 'nt'``), where nginx and certbot are+unavailable, so the tests assert the service degrades every external stage to a+warning and never raises — the Domain row is the only hard requirement.++Proving points:+- attach(..., ssl='off') records the Domain row, returns success, does NOT+ attempt a certificate, and survives with nginx unavailable+- an invalid host (no dot) returns {'success': False} and records nothing+- the DNS best-effort result is captured and its "add manually" message+ surfaces as a warning+- ssl='auto' calls obtain_certificate; a failed cert degrades to a warning+ (attach still succeeds) and a successful cert sets ssl_enabled + paths+- make_primary re-points the primary domain+- re-attaching the same host is idempotent (created=False, no duplicate row)+"""+import pytest++from app import db+from app.models import Application, User+from app.models.domain import Domain+from app.services.domain_attach_service import DomainAttachService+from app.services.dns_provider_service import DNSProviderService+from app.services.site_domain_service import SiteDomainService+from app.services.ssl_service import SSLService+++# ── helpers ──────────────────────────────────────────────────────────────────++def _owner(username='testadmin'):+ """The admin user the auth_headers fixture creates, or a fresh one."""+ user = User.query.filter_by(username=username).first()+ if user:+ return user+ from werkzeug.security import generate_password_hash+ user = User(email=f'{username}@test.local', username=username,+ password_hash=generate_password_hash('x'),+ role=User.ROLE_ADMIN, is_active=True)+ db.session.add(user)+ db.session.commit()+ return user+++def _mk_app(name='attach-app', app_type='docker', port=8300, **kw):+ a = Application(name=name, app_type=app_type, user_id=_owner().id, port=port, **kw)+ db.session.add(a)+ db.session.commit()+ return a++[email protected](autouse=True)+def _hermetic(monkeypatch):+ """Keep every test offline: DNS never touches a provider, and the nginx+ write is a no-op. Individual tests override these as needed."""+ monkeypatch.setattr(DNSProviderService, 'ensure_a_record',+ classmethod(lambda cls, host, ip: {'created': False,+ 'reason': 'no_provider',+ 'message': f'add {host} manually'}))+ monkeypatch.setattr(SiteDomainService, 'write_app_vhost',+ classmethod(lambda cls, a, force_type=None: {'nginx': None, 'warning': None}))+++# ── core attach ──────────────────────────────────────────────────────────────++def test_attach_ssl_off_creates_domain_and_succeeds(client, auth_headers, app, monkeypatch):+ """The headline case: attach a domain with SSL off. A Domain row is created,+ success is True, and nothing raises despite nginx being unavailable."""+ # Assert SSL is never attempted when ssl='off'.+ monkeypatch.setattr(SSLService, 'obtain_certificate',+ classmethod(lambda cls, *a, **kw:+ (_ for _ in ()).throw(AssertionError('SSL must not run'))))++ app_row = _mk_app(name='attach-off')+ result = DomainAttachService.attach(app_row, 'foo.example.com', ssl='off')++ assert result['success'] is True+ assert result['domain'] == 'foo.example.com'+ assert result['created'] is True+ assert result['ssl'] == {'enabled': False}+ row = Domain.query.filter_by(name='foo.example.com', application_id=app_row.id).first()+ assert row is not None+ assert row.ssl_enabled is not True+++def test_dns_result_captured_and_warned(client, auth_headers, app):+ app_row = _mk_app(name='attach-dns')+ result = DomainAttachService.attach(app_row, 'bar.example.com', ssl='off')+ assert result['dns']['reason'] == 'no_provider'+ assert any('add bar.example.com manually' in w for w in result['warnings'])+++def test_invalid_host_returns_failure(client, auth_headers, app):+ """A host with no dot is rejected and records nothing."""+ app_row = _mk_app(name='attach-bad')+ result = DomainAttachService.attach(app_row, 'nodothost', ssl='off')+ assert result['success'] is False+ assert 'error' in result+ assert Domain.query.filter_by(application_id=app_row.id).count() == 0+++def test_full_url_is_normalized_to_host(client, auth_headers, app):+ app_row = _mk_app(name='attach-url')+ result = DomainAttachService.attach(app_row, 'https://Site.Example.com:8443/path',+ ssl='off')+ assert result['success'] is True+ assert result['domain'] == 'site.example.com'+ assert Domain.query.filter_by(name='site.example.com').first() is not None+++# ── idempotency + primary ────────────────────────────────────────────────────++def test_reattach_is_idempotent(client, auth_headers, app):+ app_row = _mk_app(name='attach-idem')+ first = DomainAttachService.attach(app_row, 'idem.example.com', ssl='off')+ second = DomainAttachService.attach(app_row, 'idem.example.com', ssl='off')+ assert first['created'] is True+ assert second['created'] is False+ assert Domain.query.filter_by(name='idem.example.com').count() == 1+++def test_make_primary_repoints_primary(client, auth_headers, app):+ app_row = _mk_app(name='attach-primary')+ db.session.add(Domain(name='old.example.com', is_primary=True, application_id=app_row.id))+ db.session.commit()++ result = DomainAttachService.attach(app_row, 'new.example.com', ssl='off',+ make_primary=True)+ assert result['success'] is True+ old = Domain.query.filter_by(name='old.example.com').first()+ new = Domain.query.filter_by(name='new.example.com').first()+ assert old.is_primary is False+ assert new.is_primary is True+++def test_host_owned_by_other_app_is_rejected(client, auth_headers, app):+ a1 = _mk_app(name='attach-owner-1')+ a2 = _mk_app(name='attach-owner-2')+ assert DomainAttachService.attach(a1, 'shared.example.com', ssl='off')['success'] is True+ result = DomainAttachService.attach(a2, 'shared.example.com', ssl='off')+ assert result['success'] is False+ assert 'another app' in result['error']+++# ── SSL best-effort ──────────────────────────────────────────────────────────++def test_ssl_auto_failure_degrades_to_warning(client, auth_headers, app, monkeypatch):+ """A cert failure must never fail the attach — it becomes a warning."""+ monkeypatch.setattr(SSLService, 'obtain_certificate',+ classmethod(lambda cls, domains, email, **kw:+ {'success': False, 'error': 'DNS not propagated'}))+ app_row = _mk_app(name='attach-ssl-fail')+ result = DomainAttachService.attach(app_row, 'ssl.example.com', ssl='auto')+ assert result['success'] is True+ assert result['ssl']['enabled'] is False+ assert result['ssl']['error'] == 'DNS not propagated'+ assert any('HTTPS is not set up yet' in w for w in result['warnings'])+++def test_ssl_auto_success_sets_flags(client, auth_headers, app, monkeypatch):+ monkeypatch.setattr(SSLService, 'obtain_certificate',+ classmethod(lambda cls, domains, email, **kw:+ {'success': True,+ 'certificate_path': '/c/fullchain.pem',+ 'private_key_path': '/c/privkey.pem'}))+ from app.services.nginx_service import NginxService+ monkeypatch.setattr(NginxService, 'add_ssl_to_site',+ classmethod(lambda cls, name, cert, key: {'success': True}))++ app_row = _mk_app(name='attach-ssl-ok')+ result = DomainAttachService.attach(app_row, 'https.example.com', ssl='auto')+ assert result['success'] is True+ assert result['ssl'] == {'enabled': True}+ row = Domain.query.filter_by(name='https.example.com').first()+ assert row.ssl_enabled is True+ assert row.ssl_certificate_path == '/c/fullchain.pem'+ assert row.ssl_key_path == '/c/privkey.pem'diff --git a/backend/tests/test_manifest_apply.py b/backend/tests/test_manifest_apply.pynew file mode 100644index 00000000..955ca2d1--- /dev/null+++ b/backend/tests/test_manifest_apply.py@@ -0,0 +1,168 @@+"""Proving tests for Phase 2 — the manifest apply engine (plan 17)."""++import pytest++import app.models.application_manifest # noqa: F401+from app.services.manifest_spec_service import ManifestSpecService+from app.services.manifest_apply_service import ManifestApplyService+++MANIFEST = {+ 'version': 1,+ 'services': [+ {+ 'name': 'api', 'type': 'web', 'port': 8000, 'healthCheckPath': '/health',+ 'envVars': [{'key': 'LOG_LEVEL', 'value': 'info'},+ {'key': 'SECRET_TOKEN', 'fromSecret': 'tok'}],+ 'disks': [{'name': 'uploads', 'mountPath': '/data/uploads',+ 'backup': {'schedule': 'daily', 'retain': 7}}],+ },+ {'name': 'db', 'type': 'postgres', 'version': '16',+ 'disk': {'size': '10GB', 'backup': {'schedule': 'daily', 'retain': 7}}},+ ],+ 'domains': [{'host': 'api.example.com', 'service': 'api', 'ssl': 'auto'}],+}+++def project(app):+ from app import db+ from app.models import Project, Environment+ from app.services.workspace_service import WorkspaceService+ ws = WorkspaceService.ensure_default_workspace()+ proj = Project(workspace_id=ws.id, name='Shop', slug='shop')+ db.session.add(proj)+ db.session.commit()+ env = Environment(project_id=proj.id, name='Production', slug='production', is_default=True)+ db.session.add(env)+ db.session.commit()+ return proj+++def owner(app):+ from app import db+ from app.models import User+ user = User.query.filter_by(username='testadmin').first()+ if not user:+ user = User(username='testadmin', email='[email protected]', role='admin')+ if hasattr(user, 'set_password'):+ user.set_password('admin')+ db.session.add(user)+ db.session.commit()+ return user++[email protected](autouse=True)+def _stub_side_effects(monkeypatch):+ # avoid Docker / nginx / DNS in the harness+ from app.services.docker_service import DockerService+ from app.services.domain_attach_service import DomainAttachService+ monkeypatch.setattr(DockerService, 'create_volume',+ classmethod(lambda cls, name, driver='local': {'success': True}))+ def _fake_attach(cls, app, host, ssl='auto', email=None, make_primary=False):+ # realistic: create the Domain row so idempotence is genuinely exercised+ from app import db as _db+ from app.models.domain import Domain+ if not any(d.name == host for d in (app.domains or [])):+ _db.session.add(Domain(name=host, application_id=app.id, is_primary=False))+ _db.session.commit()+ return {'success': True, 'domain': host, 'created': True, 'warnings': []}+ monkeypatch.setattr(DomainAttachService, 'attach', classmethod(_fake_attach))+++def test_plan_is_ordered(project):+ n = ManifestSpecService.normalize(MANIFEST)+ plan = ManifestApplyService.plan(project, n)+ types = [s['type'] for s in plan['steps']]+ # dbs before consumers, domains last+ assert 'provision_db' in types+ assert types.index('provision_db') < types.index('create_app')+ assert types[-1] == 'attach_domain'+ # every declared piece shows up+ assert 'set_env' in types+ assert 'ensure_volume' in types+ assert types.count('upsert_backup_policy') == 2 # db + files+++def test_apply_materializes_and_is_idempotent(project, owner):+ from app.models import Application+ from app.models.managed_database import ManagedDatabase+ from app.models.backup_policy import BackupPolicy+ n = ManifestSpecService.normalize(MANIFEST)++ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ assert result['success'] is True, result+ assert result['applied'] >= 6++ api = Application.query.filter_by(project_id=project.id, name='api').first()+ assert api is not None+ assert api.port == 8000+ assert api.healthcheck_path == '/health'+ assert api.source == 'manifest'++ # env literal set, secret ref NOT applied in Phase 2+ from app.services.env_service import EnvService+ env = EnvService.get_env_dict(api.id)+ assert env.get('LOG_LEVEL') == 'info'+ assert 'SECRET_TOKEN' not in env++ # managed db recorded+ mdb = ManagedDatabase.query.filter_by(engine='postgresql', name='db').first()+ assert mdb is not None++ # backup policies: files (app) + database+ assert BackupPolicy.query.filter_by(target_type='files', target_id=api.id).count() == 1+ assert BackupPolicy.query.filter_by(target_type='database', target_id=mdb.id).count() == 1++ # volume created+ assert any(v.mount_path == '/data/uploads' for v in api.volumes)++ # IDEMPOTENCE: a second plan is empty+ plan2 = ManifestApplyService.plan(project, n)+ assert plan2['step_count'] == 0, plan2['summary']+++def test_apply_records_job(project, owner):+ from app.models.deployment_job import DeploymentJob+ n = ManifestSpecService.normalize(MANIFEST)+ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ job = DeploymentJob.query.get(result['job_id'])+ assert job is not None+ assert job.kind == 'manifest.apply'+ assert job.status == 'succeeded'+++def test_plan_and_apply_endpoints(client, auth_headers, project):+ # plan (dry-run)+ resp = client.post('/api/v1/manifests/plan', headers=auth_headers,+ json={'project_id': project.id, 'manifest': MANIFEST})+ assert resp.status_code == 200, resp.get_json()+ plan = resp.get_json()['plan']+ assert plan['step_count'] > 0++ # apply+ resp = client.post('/api/v1/manifests/apply', headers=auth_headers,+ json={'project_id': project.id, 'manifest': MANIFEST})+ assert resp.status_code == 200, resp.get_json()+ assert resp.get_json()['success'] is True++ # stored manifest is now retrievable + marked applied+ resp = client.get(f'/api/v1/manifests?project_id={project.id}', headers=auth_headers)+ assert resp.status_code == 200+ stored = resp.get_json()['manifest']+ assert stored['status'] == 'applied'++ # re-plan through the API is empty (idempotent)+ resp = client.post('/api/v1/manifests/plan', headers=auth_headers,+ json={'project_id': project.id})+ assert resp.get_json()['plan']['step_count'] == 0+++def test_redis_declared_but_warns(project, owner):+ n = ManifestSpecService.normalize({'version': 1,+ 'services': [{'name': 'cache', 'type': 'redis'}]})+ plan = ManifestApplyService.plan(project, n)+ assert plan['steps'][0]['type'] == 'warn'+ result = ManifestApplyService.apply(project, n, user_id=owner.id)+ assert result['success'] is True