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: provision isolated generic previews with retryable resource cleanup
Juan Denis5a13a0dfb167
diff --git a/backend/app/api/webhooks.py b/backend/app/api/webhooks.pyindex 24f45ce7..891ce00c 100644--- a/backend/app/api/webhooks.py+++ b/backend/app/api/webhooks.py@@ -189,24 +189,13 @@ def receive_pull_request(token):'pr_title': pr.get('pr_title'),}}- # On close we destroy by preview-id (the PR number maps to exactly one- # preview row); resolving it here avoids a full sync that — with no- # connected provider — would otherwise tear down every preview.- if job_kind == 'preview.destroy':- from app.models.application_preview import ApplicationPreview- preview = ApplicationPreview.query.filter_by(- application_id=webhook.app_id, pr_number=pr.get('pr_number')).first()- if not preview:- return jsonify({'success': True, 'action': 'ignored',- 'reason': 'no preview for closed PR'}), 200- payload = {'preview_id': preview.id}-- # Enqueue the matching preview job. Under ENV=testing the job system is a- # no-op; never let an enqueue failure break the webhook response.+ # Reserve desired state even when the create job has not started yet.+ # A close must cancel a queued build rather than disappear for lack of a row.enqueued = Falsetry:- from app.plugins_sdk import jobs- jobs.enqueue(job_kind, payload)+ from app.services.previews.requests import enqueue+ enqueue(webhook.app_id, payload['pr'],+ action='destroy' if job_kind == 'preview.destroy' else 'create')enqueued = Trueexcept Exception as exc:logger.warning('failed to enqueue %s for app %s: %s',diff --git a/backend/app/models/application_preview.py b/backend/app/models/application_preview.pyindex 1f35fd58..4688adbb 100644--- a/backend/app/models/application_preview.py+++ b/backend/app/models/application_preview.py@@ -48,6 +48,12 @@ class ApplicationPreview(TimestampMixin, JsonColumnMixin, db.Model):# when Docker isn't available, e.g. dev/test).container_ids = db.Column(db.Text, nullable=True)+ # Durable intent ledger: written before external effects, retained on cleanup failure.+ request_token = db.Column(db.String(32), nullable=True)+ requested_action = db.Column(db.String(16), nullable=True)+ runtime_state = db.Column(db.Text, nullable=True)+ error_message = db.Column(db.Text, nullable=True)+commit_sha = db.Column(db.String(64), nullable=True)expires_at = db.Column(db.DateTime, nullable=True)@@ -60,6 +66,12 @@ class ApplicationPreview(TimestampMixin, JsonColumnMixin, db.Model):def set_container_ids(self, ids):self._json_write('container_ids', list(ids or []), falsy='[]')+ def get_runtime_state(self):+ return self._json_read('runtime_state', {}, expect=dict)++ def set_runtime_state(self, state):+ self._json_write('runtime_state', state, falsy='{}')+def to_dict(self):container_ids = self.get_container_ids()# Older generic previews were marked running after config generation@@ -75,11 +87,11 @@ class ApplicationPreview(TimestampMixin, JsonColumnMixin, db.Model):'branch': self.branch,'status': status,'status_reason': (- 'No provisioned runtime is recorded for this preview.'- if status == self.STATUS_UNAVAILABLE else None+ self.error_message or ('No provisioned runtime is recorded for this preview.'+ if status == self.STATUS_UNAVAILABLE else None)),'domain': self.domain,- 'url': (f'https://{self.domain}'+ 'url': (f"{self.get_runtime_state().get('scheme', 'https')}://{self.domain}"if self.domain and status == self.STATUS_RUNNING and container_ids else None),'container_ids': container_ids,'commit_sha': self.commit_sha,@@ -107,6 +119,7 @@ class ApplicationPreviewSettings(TimestampMixin, db.Model):application = db.relationship('Application',backref=db.backref('preview_settings', uselist=False))+ inherit_environment = db.Column(db.Boolean, nullable=False, default=False, server_default='0')enabled = db.Column(db.Boolean, default=False, nullable=False)domain_template = db.Column(db.String(255), default=DEFAULT_DOMAIN_TEMPLATE, nullable=False)@@ -120,6 +133,7 @@ class ApplicationPreviewSettings(TimestampMixin, db.Model):return {'application_id': self.application_id,'enabled': bool(self.enabled),+ 'inherit_environment': bool(self.inherit_environment),'domain_template': self.domain_template or self.DEFAULT_DOMAIN_TEMPLATE,'target_server_id': self.target_server_id,'ttl_days': self.ttl_days,diff --git a/backend/app/services/build_service.py b/backend/app/services/build_service.pyindex ff382973..8d609ff9 100644--- a/backend/app/services/build_service.py+++ b/backend/app/services/build_service.py@@ -622,6 +622,17 @@ class BuildService:if not build_config:return {'success': False, 'error': 'Build is not set up for this service'}+ return cls.build_from_config(app_id, build_config, no_cache=no_cache,+ log_callback=log_callback, image_tag=image_tag)++ @classmethod+ def build_from_config(cls, app_id, build_config, no_cache=False,+ log_callback=None, image_tag=None):+ """Build an explicit workspace without changing an app's saved config.++ Isolated consumers must supply their own log namespace and image tag.+ The production build() entry point delegates here too.+ """app_path = build_config['app_path']build_method = build_config.get('build_method', 'auto')timeout = build_config.get('timeout', cls.DEFAULT_TIMEOUT)diff --git a/backend/app/services/docker_service.py b/backend/app/services/docker_service.pyindex 20fe6842..5684b07e 100644--- a/backend/app/services/docker_service.py+++ b/backend/app/services/docker_service.py@@ -309,7 +309,7 @@ class DockerService:@staticmethoddef run_container(image, name=None, ports=None, volumes=None, env=None,- network=None, restart_policy='unless-stopped', command=None, detach=True):+ network=None, restart_policy='unless-stopped', command=None, detach=True, labels=None):"""Run a new container (create and start)."""try:cmd = ['run']@@ -332,6 +332,9 @@ class DockerService:for key, value in env.items():cmd.extend(['-e', f'{key}={value}'])+ for key, value in (labels or {}).items():+ cmd.extend(['--label', f'{key}={value}'])+if network:cmd.extend(['--network', network])diff --git a/backend/app/services/preview_service.py b/backend/app/services/preview_service.pyindex 9c75d567..e90d7cfc 100644--- a/backend/app/services/preview_service.py+++ b/backend/app/services/preview_service.py@@ -171,6 +171,10 @@ class PreviewService:row = ApplicationPreviewSettings(application_id=application_id)db.session.add(row)+ if 'inherit_environment' in settings:+ if not isinstance(settings['inherit_environment'], bool):+ raise ValueError('inherit_environment must be a boolean')+ row.inherit_environment = settings['inherit_environment']if 'enabled' in settings:row.enabled = bool(settings['enabled'])if 'domain_template' in settings and settings['domain_template']:@@ -242,7 +246,16 @@ class PreviewService:# ------------------------------------------------------------------ #@classmethod- def create_preview(cls, app, pr_payload):+ def create_preview(cls, app, pr_payload, request_payload=None):+ from app.services.deploy_lock import deploy_lock+ with deploy_lock(app.id, 'preview deploy'):+ from app.services.previews.requests import current+ if request_payload and not current(request_payload):+ return {'skipped': True, 'reason': 'superseded'}+ return cls._create_preview_locked(app, pr_payload)++ @classmethod+ def _create_preview_locked(cls, app, pr_payload):"""Create (or update-in-place) a preview for a PR. Best-effort.Writes/updates an :class:`ApplicationPreview` row, renders the domain,@@ -254,10 +267,15 @@ class PreviewService:from app.models.application_preview import ApplicationPreviewtry:+ db.session.refresh(app)+ if app.deleted_at is not None:+ return {'error': 'Service not found'}pr_number = cls._pr_field(pr_payload, 'pr_number', 'number')if pr_number is None:return {'error': 'pr_number is required'}pr_number = int(pr_number)+ if pr_number <= 0:+ return {'error': 'PR number must be positive'}branch = cls._pr_field(pr_payload, 'branch', 'head_ref', 'head')pr_title = cls._pr_field(pr_payload, 'pr_title', 'title')commit_sha = cls._pr_field(pr_payload, 'commit_sha', 'sha', 'head_sha')@@ -280,8 +298,8 @@ class PreviewService:preview.deleted_at = Nonettl_days = getattr(settings, 'ttl_days', None)- if ttl_days:- preview.expires_at = datetime.utcnow() + timedelta(days=int(ttl_days))+ preview.expires_at = (datetime.utcnow() + timedelta(days=int(ttl_days))+ if ttl_days else None)db.session.commit()@@ -295,6 +313,8 @@ class PreviewService:preview.status = ApplicationPreview.STATUS_FAILEDif provisioned.get('container_ids'):preview.set_container_ids(provisioned['container_ids'])+ elif not preview.get_runtime_state().get('container'):+ preview.set_container_ids([])db.session.commit()return preview.to_dict()except Exception as exc:@@ -309,8 +329,8 @@ class PreviewService:def _provision(cls, app, preview):"""Best-effort real provisioning. Returns ``{'ok': bool, 'container_ids': [...]}``.- WordPress delegates to its preview hook. Generic config generation is- not provisioning: until a runtime provisioner exists, report unsupported.+ WordPress delegates to its preview hook; generic runtimes have a separate+ journalled provisioner reusing the standard container builders.A provider must explicitly report success and return runtime identifiers."""try:@@ -329,24 +349,29 @@ class PreviewService:except Exception as exc:logger.info('WP preview provisioning unavailable: %s', exc)return {'ok': False, 'container_ids': []}- # Non-WP: clone the manifest-resolved config (env + per-preview- # overrides + domain) when the app is manifest-managed (#20). The- # resolved config is the portable unit; a full Docker clone for- # generic apps remains best-effort future work.- manifest_preview = None- try:- from app.services.manifest_preview_service import ManifestPreviewService- manifest_preview = ManifestPreviewService.build_preview_config(app, preview)- except Exception as exc:- logger.info('manifest preview config unavailable: %s', exc)- return {'ok': False, 'unsupported': True, 'container_ids': [],- 'manifest_preview': manifest_preview}+ from app.services.previews.provisioner import provision+ return provision(app, preview, cls.get_settings(app.id))except Exception as exc:logger.info('preview provisioning unavailable: %s', exc)return {'ok': False, 'container_ids': []}@classmethod- def destroy_preview(cls, preview_id):+ def destroy_preview(cls, preview_id, request_payload=None):+ from app.models.application_preview import ApplicationPreview+ from app.services.deploy_lock import deploy_lock+ row = ApplicationPreview.query.get(preview_id)+ if not row:+ return {'error': 'preview not found'}+ with deploy_lock(row.application_id, 'preview cleanup'):+ from app.services.previews.requests import current+ if request_payload and not current(request_payload):+ return {'skipped': True, 'reason': 'superseded'}+ from app import db+ db.session.refresh(row)+ return cls._destroy_preview_locked(preview_id)++ @classmethod+ def _destroy_preview_locked(cls, preview_id):"""Tear down a preview and mark it destroyed. Best-effort; never raises."""from app import dbfrom app.models.application_preview import ApplicationPreview@@ -368,6 +393,10 @@ class PreviewService:except Exception:pass+ if preview.runtime_state:+ from app.services.previews.runtime import cleanup+ cleanup(preview)+# Best-effort WordPress teardown.if app is not None and getattr(app, 'app_type', None) == 'wordpress':try:@@ -391,7 +420,11 @@ class PreviewService:db.session.rollback()except Exception:pass- return {'error': str(exc)}+ if preview:+ preview.status = ApplicationPreview.STATUS_FAILED+ preview.error_message = 'Preview cleanup failed; retry deletion.'+ db.session.commit()+ return {'error': 'Preview cleanup failed; retry deletion.'}@classmethoddef sync_previews(cls, application_id):@@ -412,6 +445,8 @@ class PreviewService:return {'error': 'Service not found'}open_prs = cls._fetch_open_prs(app)+ if open_prs is None:+ return {'error': 'Open PR discovery is unavailable; existing previews were left unchanged.'}active = ApplicationPreview.query.filter(ApplicationPreview.application_id == application_id,ApplicationPreview.status != ApplicationPreview.STATUS_DESTROYED,@@ -449,7 +484,7 @@ class PreviewService:return prs if isinstance(prs, list) else []except Exception as exc:logger.debug('open-PR listing unavailable for app %s: %s', app.id, exc)- return []+ return None@classmethoddef expire_stale(cls):@@ -464,9 +499,8 @@ class PreviewService:ApplicationPreview.expires_at < now,ApplicationPreview.status != ApplicationPreview.STATUS_DESTROYED,).all()- for preview in stale:- cls.destroy_preview(preview.id)- return {'expired': len(stale)}+ expired = sum(cls.destroy_preview(p.id).get('status') == 'destroyed' for p in stale)+ return {'expired': expired, 'failed': len(stale) - expired}except Exception as exc:logger.warning('expire_stale failed: %s', exc)return {'expired': 0, 'error': str(exc)}@@ -484,17 +518,30 @@ class PreviewService:id=payload.get('application_id')).first()if not app:return {'error': 'Service not found'}- return cls.create_preview(app, payload.get('pr') or payload)+ result = cls.create_preview(app, payload.get('pr') or payload, request_payload=payload)+ if result.get('skipped'):+ return result+ if result.get('error') or result.get('status') != 'running':+ raise RuntimeError(result.get('error') or result.get('status_reason') or 'Preview was not deployed')+ return result@classmethoddef _job_destroy(cls, job):payload = job.get_payload() or {}- return cls.destroy_preview(payload.get('preview_id'))+ result = cls.destroy_preview(payload.get('preview_id'), request_payload=payload)+ if result.get('error'):+ raise RuntimeError(result['error'])+ return result@classmethoddef _job_sync(cls, job):payload = job.get_payload() or {}- return cls.sync_previews(payload.get('application_id'))+ if payload.get('pr'):+ return cls._job_create(job)+ result = cls.sync_previews(payload.get('application_id'))+ if result.get('error'):+ raise RuntimeError(result['error'])+ return result@classmethoddef _job_expire(cls, _job):diff --git a/backend/app/services/previews/__init__.py b/backend/app/services/previews/__init__.pynew file mode 100644index 00000000..594f1716--- /dev/null+++ b/backend/app/services/previews/__init__.py@@ -0,0 +1 @@+"""Isolated generic preview planning, source preparation and runtime lifecycle."""diff --git a/backend/app/services/previews/plan.py b/backend/app/services/previews/plan.pynew file mode 100644index 00000000..83dd3835--- /dev/null+++ b/backend/app/services/previews/plan.py@@ -0,0 +1,53 @@+"""Pure preview identity and eligibility; no host operations."""+import re+from pathlib import Path+from app.services.nginx.validation import _validate_domain+from app.utils.git_security import validate_repo_url, validate_ref_name+++class PreviewError(ValueError):+ pass+++def validate(app, preview, settings, git_config):+ if app.server_id or settings.target_server_id:+ raise PreviewError('Generic previews currently require a local server.')+ if app.compose_file or app.managed_by in ('docker_compose', 'systemd'):+ raise PreviewError('Compose and systemd previews are not supported by this provisioner.')+ if app.ingress_plane not in (None, '', 'nginx'):+ raise PreviewError('Generic previews currently require nginx ingress.')+ if not app.port or not 1 <= app.port <= 65535:+ raise PreviewError('Configure the application container port before deploying a preview.')+ if not preview.domain or len(preview.domain) > 253 or not _validate_domain(preview.domain):+ raise PreviewError('Invalid preview domain.')+ if not isinstance(preview.pr_number, int) or preview.pr_number <= 0:+ raise PreviewError('PR number must be a positive integer.')+ if not preview.branch or validate_ref_name(preview.branch, 'branch'):+ raise PreviewError('A valid branch in the configured repository is required.')+ if not re.fullmatch(r'[0-9a-fA-F]{40}|[0-9a-fA-F]{64}', preview.commit_sha or ''):+ raise PreviewError('An exact full commit SHA is required.')+ if not git_config or validate_repo_url(git_config.get('repo_url')):+ raise PreviewError('Configure a valid Git repository for this application first.')+++def identity(preview_id, token):+ if not isinstance(preview_id, int) or preview_id <= 0 or not re.fullmatch(r'[0-9a-f]{32}', token):+ raise PreviewError('Invalid preview resource identity.')+ return f'serverkit-preview-{preview_id}-{token}'+++def workspace(root, preview_id, token):+ # Never accept stored/PR-provided paths as cleanup targets.+ name = identity(preview_id, token)+ base = Path(root).resolve()+ target = base / name+ if target.is_symlink() or target.resolve().parent != base:+ raise PreviewError('Preview workspace escaped its managed directory.')+ return target+++def relative_file(root, name):+ path = Path(root) / name+ if Path(name).is_absolute() or not path.resolve().is_relative_to(Path(root).resolve()):+ raise PreviewError('Build path must stay inside the preview checkout.')+ return pathdiff --git a/backend/app/services/previews/provisioner.py b/backend/app/services/previews/provisioner.pynew file mode 100644index 00000000..a74d905e--- /dev/null+++ b/backend/app/services/previews/provisioner.py@@ -0,0 +1,67 @@+"""Generic preview transaction: validate, journal, build, gate, publish; compensate failures."""+import uuid+from app import db+from app.models import Domain+from app.models.application_preview import ApplicationPreview+from app.services.git_service import GitService+from app.services.nginx_service import NginxService+from . import runtime, source+from .plan import PreviewError, validate, identity, workspace+++def check_domain(preview):+ domain = preview.domain.lower()+ if Domain.query_active().filter(db.func.lower(Domain.name) == domain).first():+ raise PreviewError('Preview domain is already assigned to an application.')+ if ApplicationPreview.query.filter(+ ApplicationPreview.id != preview.id,+ db.func.lower(ApplicationPreview.domain) == domain,+ ApplicationPreview.status != 'destroyed',+ ).first():+ raise PreviewError('Preview domain is already assigned to another preview.')+ owned = preview.get_runtime_state().get('token')+ own_name = identity(preview.id, owned) if owned else None+ for site in NginxService.list_sites():+ if site['name'] != own_name and domain in [d.lower() for d in site.get('domains', [])]:+ raise PreviewError('Preview domain is already configured in nginx.')+++def provision(app, preview, settings):+ config = GitService.get_app_config(app.id)+ request_token = preview.request_token+ try:+ validate(app, preview, settings, config)+ check_domain(preview)+ # Stop/recreate semantics are deliberate: cleanup must finish before a+ # new attempt. We never lose ownership of an abandoned generation.+ runtime.cleanup(preview)+ state = {'token': uuid.uuid4().hex}+ runtime.save(preview, state)+ target = workspace(runtime.ROOT, preview.id, state['token'])+ target.parent.mkdir(parents=True, exist_ok=True)+ name = identity(preview.id, state['token'])+ state['source'] = True+ runtime.save(preview, state)+ source.prepare(app, preview, target, config['repo_url'])+ state['image'] = True+ runtime.save(preview, state)+ source.build(app, preview, target, name + ':preview')+ runtime.start(app, preview, state)+ db.session.refresh(preview, ['request_token', 'requested_action'])+ db.session.refresh(app, ['deleted_at'])+ if app.deleted_at or preview.request_token != request_token or preview.requested_action == 'destroy':+ raise PreviewError('Preview request was superseded or its application was deleted.')+ runtime.publish(preview, state)+ preview.error_message = None+ return {'ok': True, 'container_ids': [state['container_id']]}+ except Exception as exc:+ # Only controlled diagnostics go to the browser; host errors may carry+ # credentials or environment values. The journal survives cleanup errors.+ error = str(exc) if isinstance(exc, PreviewError) else 'Preview provisioning failed.'+ try:+ runtime.cleanup(preview)+ except Exception:+ error += ' Cleanup is incomplete; retry deletion before deploying again.'+ preview.error_message = error+ db.session.commit()+ return {'ok': False, 'container_ids': [], 'error': error}diff --git a/backend/app/services/previews/requests.py b/backend/app/services/previews/requests.pynew file mode 100644index 00000000..699f2bbd--- /dev/null+++ b/backend/app/services/previews/requests.py@@ -0,0 +1,40 @@+"""Short request reservations, separate from long-running deployment locks."""+import uuid+from app import db+from app.models.application_preview import ApplicationPreview+from app.jobs.service import JobService+from app.services.deploy_lock import deploy_lock+from .plan import PreviewError+++def enqueue(app_id, pr, action='create'):+ try:+ number = int(pr.get('pr_number'))+ except (TypeError, ValueError):+ raise PreviewError('A positive PR number is required.')+ if number <= 0 or action not in ('create', 'destroy'):+ raise PreviewError('Invalid preview request.')+ # Distinct from the app deploy lock: a close can supersede an in-flight+ # build immediately instead of blocking the webhook for several minutes.+ with deploy_lock(f'preview-request-{app_id}', 'preview request'):+ row = ApplicationPreview.query.filter_by(application_id=app_id, pr_number=number).first()+ if row is None:+ row = ApplicationPreview(application_id=app_id, pr_number=number, status='queued')+ db.session.add(row)+ row.request_token = uuid.uuid4().hex+ row.requested_action = action+ db.session.commit()+ return JobService.enqueue('preview.' + action, {+ 'application_id': app_id, 'preview_id': row.id, 'pr': pr,+ 'request_token': row.request_token,+ }, max_attempts=1, owner_type='application', owner_id=str(app_id))+++def current(payload):+ if not payload.get('request_token'):+ return True # compatibility with older queued jobs+ row = db.session.get(ApplicationPreview, payload.get('preview_id'))+ if not row:+ return False+ db.session.refresh(row, ['request_token'])+ return row.request_token == payload['request_token']diff --git a/backend/app/services/previews/runtime.py b/backend/app/services/previews/runtime.pynew file mode 100644index 00000000..cb5cdd15--- /dev/null+++ b/backend/app/services/previews/runtime.py@@ -0,0 +1,123 @@+"""Host effects for one journalled preview generation; never operate on parent resources."""+import json+import shutil+from pathlib import Path+from app import db, paths+from app.services.docker_service import DockerService+from app.services.nginx_service import NginxService+from app.services.site_domain_service import SiteDomainService+from app.services import health_gate+from .plan import PreviewError, identity, workspace++ROOT = Path(paths.SERVERKIT_DIR) / 'previews'+LABEL = 'serverkit.preview'+++def save(preview, state):+ preview.set_runtime_state(state)+ db.session.commit()+++def inspect(kind, name):+ result = DockerService.run([kind, 'inspect', name], timeout=30)+ if result.get('success'):+ return json.loads(result['output'])[0]+ error = (result.get('error') or '').lower()+ if 'no such' in error:+ return None+ raise PreviewError('Cannot inspect preview resources; cleanup must be retried.')+++def start(app, preview, state):+ name = identity(preview.id, state['token'])+ state['container'] = True+ save(preview, state) # intent before docker run, even if it partially fails+ env = {'SERVERKIT_PREVIEW': 'true', 'SERVERKIT_PR_NUMBER': str(preview.pr_number),+ 'SERVERKIT_PREVIEW_BRANCH': preview.branch}+ from app.services.preview_service import PreviewService+ if PreviewService.get_settings(app.id).inherit_environment:+ from app.services.env_service import EnvService+ entries, complete = EnvService._effective_entries(app)+ if not complete:+ raise PreviewError('Inherited environment is incomplete; preview deployment stopped.')+ env = {**{key: value['value'] for key, value in entries.items()}, **env}+ result = DockerService.run_container(+ image=name + ':preview', name=name, ports=[f'127.0.0.1::{app.port}'],+ env=env, restart_policy='unless-stopped', labels={LABEL: str(preview.id)},+ )+ if not result.get('success'):+ raise PreviewError('Could not start the preview container.')+ info = inspect('container', name)+ if not info or info.get('Config', {}).get('Labels', {}).get(LABEL) != str(preview.id):+ raise PreviewError('Preview container ownership could not be verified.')+ bindings = info.get('NetworkSettings', {}).get('Ports', {}).get(f'{app.port}/tcp') or []+ binding = next((b for b in bindings if b.get('HostIp') == '127.0.0.1'), None)+ if not binding:+ raise PreviewError('Preview container has no loopback HTTP port.')+ state['port'] = int(binding['HostPort'])+ state['container_id'] = info['Id']+ save(preview, state)+ health_gate.gate_for_app(app, port=state['port'], container=name)+ info = inspect('container', name)+ if not info or not info.get('State', {}).get('Running'):+ raise PreviewError('Preview container stopped during its health check.')+++def publish(preview, state):+ name = identity(preview.id, state['token'])+ cert = key = None+ base = SiteDomainService.covering_base(preview.domain)+ # A wildcard certificate covers exactly one label, not pr.app.base.+ if base and preview.domain.endswith('.' + base) and preview.domain.count('.') == base.count('.') + 1:+ if SiteDomainService.https_enabled(base):+ cert, key = SiteDomainService.wildcard_cert_paths(base)+ state['scheme'] = 'https' if cert and key else 'http'+ state['vhost'] = True+ save(preview, state)+ result = NginxService.create_site(name, 'docker', [preview.domain],+ port=state['port'], ssl_cert=cert, ssl_key=key)+ if not result.get('success'):+ raise PreviewError('Preview routing could not be published.')+++def cleanup(preview):+ """Idempotent, fail closed. Retain each intent until its removal succeeds."""+ state = preview.get_runtime_state()+ if not state:+ if preview.runtime_state and preview.runtime_state != '{}':+ raise PreviewError('Preview resource ledger is invalid; refusing untracked cleanup.')+ return+ name = identity(preview.id, state.get('token', ''))+ target = workspace(ROOT, preview.id, state['token'])+ if state.get('vhost'):+ # delete_site historically ignores disable failures. Check disable first+ # so nginx cannot continue serving a resource reported as destroyed.+ if not NginxService.disable_site(name).get('success'):+ raise PreviewError('Preview routing cleanup failed; retry deletion.')+ if not NginxService.delete_site(name).get('success'):+ raise PreviewError('Preview vhost cleanup failed; retry deletion.')+ state['vhost'] = False+ save(preview, state)+ if state.get('container'):+ info = inspect('container', name)+ if info:+ if info.get('Config', {}).get('Labels', {}).get(LABEL) != str(preview.id):+ raise PreviewError('Refusing to delete a container without preview ownership.')+ if not DockerService.remove_container(name, force=True, volumes=True).get('success'):+ raise PreviewError('Preview container cleanup failed; retry deletion.')+ state['container'] = False+ preview.set_container_ids([])+ save(preview, state)+ if state.get('image'):+ if inspect('image', name + ':preview') is not None:+ if not DockerService.remove_image(name + ':preview', force=False).get('success'):+ raise PreviewError('Preview image cleanup failed; retry deletion.')+ state['image'] = False+ save(preview, state)+ if state.get('source'):+ if target.exists():+ shutil.rmtree(target)+ state['source'] = False+ save(preview, state)+ preview.set_container_ids([])+ save(preview, {})diff --git a/backend/app/services/previews/source.py b/backend/app/services/previews/source.pynew file mode 100644index 00000000..305114ca--- /dev/null+++ b/backend/app/services/previews/source.py@@ -0,0 +1,49 @@+"""Prepare an independent, pinned checkout and reuse the standard builders."""+import shutil+from app.services.git_service import GitService+from app.services.build_service import BuildService+from app.utils.git_security import git_argv, git_env+from app.utils.system import run_checked+from .plan import PreviewError, relative_file+++def prepare(app, preview, target, repo_url):+ result = GitService.clone_repository(str(target), repo_url, branch=preview.branch)+ if not result.get('success'):+ # Raw Git output can contain authenticated repository URLs.+ raise PreviewError('Preview repository clone failed. Check repository access and branch.')+ sha = preview.commit_sha.lower()+ # A PR must name a commit reachable from the selected same-repository branch.+ result = run_checked(git_argv('-C', str(target), 'merge-base', '--is-ancestor',+ sha, 'HEAD'), timeout=30, env=git_env())+ if not result.get('success'):+ raise PreviewError('Preview commit is not reachable from the selected repository branch.')+ result = run_checked(git_argv('-C', str(target), 'checkout', '--detach', sha),+ timeout=60, env=git_env())+ if not result.get('success'):+ raise PreviewError('Could not check out the requested preview commit.')+ # Do not send clone credentials / Git metadata into a Docker build context.+ shutil.rmtree(target / '.git')+++def build(app, preview, target, image):+ config = dict(BuildService.get_app_build_config(app.id) or {})+ config['app_path'] = str(target)+ method = config.get('build_method', 'auto')+ if method == 'auto':+ method = BuildService.detect_build_method(str(target))['build_method']+ if method not in ('dockerfile', 'nixpacks'):+ raise PreviewError('Previews require a Dockerfile or container buildpack; host-command builds are disabled.')+ config['build_method'] = method+ relative_file(target, config.get('dockerfile_path') or 'Dockerfile')+ relative_file(target, 'Dockerfile.serverkit')+ # Detect the PR's source, not the parent branch's persisted plan. Parent+ # build secrets are not implicitly handed to PR code.+ config.pop('buildpack_plan', None)+ config['build_args'] = {}+ config['env_vars'] = {}+ result = BuildService.build_from_config(+ f'preview-{preview.id}', config, image_tag=image,+ )+ if not result.get('success'):+ raise PreviewError('Preview image build failed. See the preview build logs.')diff --git a/backend/migrations/versions/111_preview_runtime.py b/backend/migrations/versions/111_preview_runtime.pynew file mode 100644index 00000000..2518dc85--- /dev/null+++ b/backend/migrations/versions/111_preview_runtime.py@@ -0,0 +1,31 @@+"""Track preview-owned resources and opt-in environment inheritance."""+import sqlalchemy as sa+from alembic import op++revision = '111_preview_runtime'+down_revision = '110_drop_workflow_schedules_job'+branch_labels = None+depends_on = None+++def upgrade():+ inspector = sa.inspect(op.get_bind())+ existing = {c['name'] for c in inspector.get_columns('application_previews')}+ for name, kind in [('request_token', sa.String(32)), ('requested_action', sa.String(16)),+ ('runtime_state', sa.Text()), ('error_message', sa.Text())]:+ if name not in existing:+ op.add_column('application_previews', sa.Column(name, kind, nullable=True))+ existing = {c['name'] for c in inspector.get_columns('application_preview_settings')}+ if 'inherit_environment' not in existing:+ op.add_column('application_preview_settings', sa.Column(+ 'inherit_environment', sa.Boolean(), nullable=False, server_default='0'))+++def downgrade():+ with op.batch_alter_table('application_preview_settings') as batch:+ batch.drop_column('inherit_environment')+ with op.batch_alter_table('application_previews') as batch:+ batch.drop_column('request_token')+ batch.drop_column('requested_action')+ batch.drop_column('error_message')+ batch.drop_column('runtime_state')diff --git a/backend/tests/test_generic_previews.py b/backend/tests/test_generic_previews.pynew file mode 100644index 00000000..cc40d21e--- /dev/null+++ b/backend/tests/test_generic_previews.py@@ -0,0 +1,208 @@+"""Generic previews: real orchestration with fake external Git/Docker/nginx effects."""+import json+from types import SimpleNamespace+import pytest+from app import db+from app.models.application_preview import ApplicationPreview+from app.services.preview_service import PreviewService+from app.services.previews import runtime, source+from app.services.previews.plan import PreviewError, identity, workspace, validate+from test_previews import _mk_app++SHA = 'a' * 40+PR = {'pr_number': 7, 'branch': 'feature/preview', 'commit_sha': SHA}+++def host(app, monkeypatch, tmp_path):+ from app.services.git_service import GitService+ from app.services.build_service import BuildService+ resources = {'containers': {}, 'images': set(), 'routes': {}, 'calls': []}+ monkeypatch.setattr(runtime, 'ROOT', tmp_path / 'previews')+ monkeypatch.setattr(BuildService, 'BUILD_LOG_DIR', str(tmp_path / 'logs'))+ monkeypatch.setattr(GitService, 'get_app_config', lambda _: {'repo_url': 'https://example.test/repo.git'})+ def prepare(parent, preview, path, url):+ resources['calls'].append(('clone', str(path), url))+ path.mkdir()+ (path / 'Dockerfile').write_text('FROM scratch')+ def build(parent, preview, path, image):+ resources['calls'].append(('build', image))+ resources['images'].add(image)+ monkeypatch.setattr(source, 'prepare', prepare)+ monkeypatch.setattr(source, 'build', build)+ def run_container(**kwargs):+ resources['calls'].append(('run', kwargs))+ name = kwargs['name']+ resources['containers'][name] = {'Id': name + '-id',+ 'Config': {'Labels': kwargs['labels']}, 'State': {'Running': True},+ 'NetworkSettings': {'Ports': {'8400/tcp': [{'HostIp': '127.0.0.1', 'HostPort': '39001'}]}}}+ return {'success': True, 'container_id': name + '-id'}+ def inspect(args, **kwargs):+ kind, _, name = args+ data = resources['containers'].get(name) if kind == 'container' else ({} if name in resources['images'] else None)+ if data is None:+ return {'success': False, 'error': 'No such object'}+ return {'success': True, 'output': json.dumps([data])}+ def remove(name, **kwargs):+ resources['calls'].append(('remove', name, kwargs))+ resources['containers'].pop(name, None)+ return {'success': True}+ def remove_image(name, **kwargs):+ resources['images'].discard(name)+ return {'success': True}+ def publish(name, kind, domains, **kwargs):+ resources['routes'][name] = domains+ return {'success': True}+ def delete(name):+ resources['routes'].pop(name, None)+ return {'success': True}+ monkeypatch.setattr(runtime.DockerService, 'run_container', run_container)+ monkeypatch.setattr(runtime.DockerService, 'run', inspect)+ monkeypatch.setattr(runtime.DockerService, 'remove_container', remove)+ monkeypatch.setattr(runtime.DockerService, 'remove_image', remove_image)+ monkeypatch.setattr(runtime.NginxService, 'list_sites', lambda: [])+ monkeypatch.setattr(runtime.NginxService, 'create_site', publish)+ monkeypatch.setattr(runtime.NginxService, 'disable_site', lambda _: {'success': True})+ monkeypatch.setattr(runtime.NginxService, 'delete_site', delete)+ monkeypatch.setattr(runtime.SiteDomainService, 'covering_base', lambda _: None)+ monkeypatch.setattr(runtime.health_gate, 'gate_for_app', lambda *a, **kw: {'status': 200})+ with app.app_context():+ parent = _mk_app(name='generic')+ parent.container_id = 'production-container'+ parent.docker_image = 'production:live'+ db.session.commit()+ PreviewService.enable_previews(parent.id, {'enabled': True, 'domain_template': 'pr-{pr_number}.test.example'})+ yield parent, resources+++def test_create_redeploy_destroy_are_isolated_and_idempotent(host):+ parent, resources = host+ first = PreviewService.create_preview(parent, PR)+ assert first['status'] == 'running', first+ assert first['url'] == 'http://pr-7.test.example'+ old_ids = first['container_ids']+ call = next(c[1] for c in resources['calls'] if c[0] == 'run')+ assert call['ports'] == ['127.0.0.1::8400']+ assert 'volumes' not in call and 'network' not in call+ assert call['env'] == {'SERVERKIT_PREVIEW': 'true', 'SERVERKIT_PR_NUMBER': '7', 'SERVERKIT_PREVIEW_BRANCH': 'feature/preview'}+ second = PreviewService.create_preview(parent, {**PR, 'commit_sha': 'b' * 40})+ assert second['status'] == 'running'+ assert second['id'] == first['id'] and second['container_ids'] != old_ids+ assert len(resources['containers']) == len(resources['images']) == len(resources['routes']) == 1+ result = PreviewService.destroy_preview(first['id'])+ assert result['status'] == 'destroyed'+ assert not resources['containers'] and not resources['images'] and not resources['routes']+ assert not list(runtime.ROOT.iterdir())+ assert PreviewService.destroy_preview(first['id'])['status'] == 'destroyed'+ db.session.refresh(parent)+ assert parent.container_id == 'production-container'+ assert parent.docker_image == 'production:live' and parent.port == 8400++[email protected]('failure', ['clone', 'build', 'start', 'health', 'route'])+def test_each_failure_compensates_owned_resources(host, monkeypatch, failure):+ parent, resources = host+ def fail(*args, **kwargs):+ raise RuntimeError('secret-diagnostic-do-not-expose')+ owner, attr = {'clone': (source, 'prepare'), 'build': (source, 'build'),+ 'start': (runtime, 'start'), 'health': (runtime.health_gate, 'gate_for_app'),+ 'route': (runtime, 'publish')}[failure]+ monkeypatch.setattr(owner, attr, fail)+ result = PreviewService.create_preview(parent, PR)+ assert result['status'] == 'failed' and result['url'] is None+ assert 'secret-diagnostic' not in str(result)+ assert not resources['containers'] and not resources['images'] and not resources['routes']+ row = db.session.get(ApplicationPreview, result['id'])+ assert row.get_runtime_state() == {}+++def test_cleanup_failure_preserves_journal_and_retry_succeeds(host, monkeypatch):+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ remove = runtime.DockerService.remove_container+ monkeypatch.setattr(runtime.DockerService, 'remove_container', lambda *a, **kw: {'success': False})+ failed = PreviewService.destroy_preview(result['id'])+ assert failed.get('error')+ row = db.session.get(ApplicationPreview, result['id'])+ assert row.status == 'failed' and row.deleted_at is None+ assert row.get_runtime_state()['container'] is True+ assert resources['containers']+ monkeypatch.setattr(runtime.DockerService, 'remove_container', remove)+ assert PreviewService.destroy_preview(result['id'])['status'] == 'destroyed'+ assert not resources['containers']+++def test_domain_conflict_prevents_host_effects(host):+ from app.models import Domain+ parent, resources = host+ db.session.add(Domain(name='pr-7.test.example', application_id=parent.id))+ db.session.commit()+ result = PreviewService.create_preview(parent, PR)+ assert result['status'] == 'failed'+ assert not resources['calls']+++def test_unsupported_target_and_bad_ref_do_not_provision(host):+ parent, resources = host+ parent.compose_file = 'compose.yml'+ db.session.commit()+ assert PreviewService.create_preview(parent, PR)['status'] == 'failed'+ parent.compose_file = None+ db.session.commit()+ assert PreviewService.create_preview(parent, {**PR, 'commit_sha': '--bad'})['status'] == 'failed'+ assert not resources['calls']+++def test_unknown_provider_does_not_destroy_existing_previews(host):+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ assert PreviewService.sync_previews(parent.id).get('error')+ assert db.session.get(ApplicationPreview, result['id']).status == 'running'+ assert resources['containers']+++def test_cleanup_rejects_missing_ownership(host):+ parent, resources = host+ result = PreviewService.create_preview(parent, PR)+ next(iter(resources['containers'].values()))['Config']['Labels'] = {}+ assert PreviewService.destroy_preview(result['id']).get('error')+ assert resources['containers']+++def test_close_supersedes_queued_create_before_row_has_runtime(host, monkeypatch):+ from app.services.previews.requests import enqueue+ from app.jobs.service import JobService+ parent, resources = host+ jobs = []+ def capture(kind, payload, **kwargs):+ job = SimpleNamespace(kind=kind, get_payload=lambda: payload)+ jobs.append(job)+ return job+ monkeypatch.setattr(JobService, 'enqueue', capture)+ enqueue(parent.id, PR)+ enqueue(parent.id, PR, action='destroy')+ assert PreviewService._job_create(jobs[0])['reason'] == 'superseded'+ assert PreviewService._job_destroy(jobs[1])['status'] == 'destroyed'+ assert not resources['calls']+++def test_close_during_build_cleans_up_without_publishing(host, monkeypatch):+ from app.services.previews.requests import enqueue+ from app.jobs.service import JobService+ parent, resources = host+ monkeypatch.setattr(JobService, 'enqueue', lambda *a, **kw: None)+ original = source.build+ def build(*args):+ original(*args)+ enqueue(parent.id, PR, action='destroy')+ monkeypatch.setattr(source, 'build', build)+ result = PreviewService.create_preview(parent, PR)+ assert result['status'] == 'failed'+ assert not resources['routes'] and not resources['containers']+++def test_cleanup_paths_cannot_escape(tmp_path):+ with pytest.raises(PreviewError):+ workspace(tmp_path, 1, '../escape')+ with pytest.raises(PreviewError):+ identity(-1, 'a' * 32)diff --git a/backend/tests/test_previews.py b/backend/tests/test_previews.pyindex 6da064d2..69126e7c 100644--- a/backend/tests/test_previews.py+++ b/backend/tests/test_previews.py@@ -156,12 +156,12 @@ def test_create_and_destroy_writes_rows_and_flips_status(app):'pr_title': 'Add X',})assert created.get('pr_number') == 12- assert created.get('status') == ApplicationPreview.STATUS_UNAVAILABLE+ assert created.get('status') == ApplicationPreview.STATUS_FAILEDassert created['url'] is Noneassert created.get('domain') # a domain was renderedrow = ApplicationPreview.query.filter_by(application_id=a.id, pr_number=12).first()- assert row is not None and row.status == ApplicationPreview.STATUS_UNAVAILABLE+ assert row is not None and row.status == ApplicationPreview.STATUS_FAILEDdestroyed = PreviewService.destroy_preview(row.id)assert destroyed.get('status') == ApplicationPreview.STATUS_DESTROYED