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
"""Generic restore-point lifecycle and adapter registry.
Adapters keep OS/provider knowledge out of this module. Each adapter may be
an object or mapping with these members::
capture(scope_id, server_id=None) -> JSON-serializable payload
restore(scope_id, payload, actor=None, server_id=None) -> result
diff(old_payload, new_payload) -> structured diff # optional
validate_restore(scope_id, payload, current_payload,
actor=None, server_id=None) -> refusals # optional
coverage -> list[str] or callable(scope_id, server_id=None) # optional
Capture is deliberately best-effort: it returns ``None`` and logs when the
adapter or database cannot produce a checkpoint. This preserves the existing
capture-before-mutation contract -- a checkpoint outage must not turn into a
configuration outage.
"""
from contextlib import contextmanager
from contextvars import ContextVar
from datetime import datetime, timedelta
import hashlib
import json
import logging
from sqlalchemy import and_, or_
from app import db
from app.exceptions import (
ApplicationError,
ConflictError,
DependencyUnavailableError,
NotFoundError,
ValidationError,
)
logger = logging.getLogger(__name__)
DEFAULT_RETENTION_DAYS = 30
DEFAULT_SCOPE_CAP = 50
BASE_COVERAGE = (
'Secrets are stored masked and are never overwritten by a restore. '
'State outside the panel (files on disk, provider-side records created '
'elsewhere, container runtime state) is outside the checkpoint.'
)
SCOPE_COVERAGE = {
'firewall': (
'Persisted panel-supported UFW rules and firewalld service, port, and '
'rich-rule families are part of this checkpoint, including matching '
'rules created outside the panel. Other firewalld families, interfaces, '
'sources, and runtime-only fail2ban/Docker chains are not captured.',
),
'dns': (
'Records that exist only at the provider and were never managed by '
'the panel are not captured.',
),
'nginx_vhost': (
'Only panel-rendered vhosts are captured. Hand-edited files in '
'sites-enabled are drift, not checkpoint content — see the Drift report.',
),
}
class RestorePointError(ValidationError):
"""Invalid restore-point operation (capture remains best-effort)."""
code = 'restore_point_invalid'
class RestorePointNotFoundError(NotFoundError):
code = 'restore_point_not_found'
class RestorePointScopeNotFoundError(NotFoundError):
code = 'restore_point_scope_not_found'
class RestorePointAdapterError(DependencyUnavailableError):
code = 'restore_point_adapter_unavailable'
class RestorePointCorruptError(ConflictError):
code = 'restore_point_corrupt'
class RestorePointRefusedError(ConflictError):
code = 'restore_point_refused'
def __init__(self, refusals):
self.refusals = list(refusals)
super().__init__(
'Restore refused by the surface safety check',
details={'refusals': self.refusals},
)
# scope_type -> adapter. The alias is intentionally public for extensions and
# for registry introspection without coupling callers to the implementation.
ADAPTERS = {}
RESTORE_POINT_ADAPTERS = ADAPTERS
# Restore adapters deliberately replay through the ordinary mutation doors.
# Hooks at those doors call auto_capture(), so suppress only those automatic
# calls while a restore is replaying. Direct capture() remains available for
# the one deliberate pre-restore checkpoint.
_AUTO_CAPTURE_SUPPRESSED = ContextVar(
'restore_point_auto_capture_suppressed', default=False,
)
def _member(adapter, name):
if isinstance(adapter, dict):
return adapter.get(name)
return getattr(adapter, name, None)
def register_adapter(scope_type, adapter=None):
"""Register (or replace) an adapter; also supports decorator use."""
if adapter is None:
return lambda value: register_adapter(scope_type, value)
if not scope_type:
raise ValueError('scope_type is required')
if not callable(_member(adapter, 'capture')):
raise ValueError('restore-point adapter requires capture()')
if not callable(_member(adapter, 'restore')):
raise ValueError('restore-point adapter requires restore()')
ADAPTERS[str(scope_type)] = adapter
return adapter
def get_adapter(scope_type):
return ADAPTERS.get(str(scope_type))
def clear_adapters():
"""Test/plugin-reload helper."""
ADAPTERS.clear()
def auto_capture_is_suppressed():
"""Let mutation doors avoid pre-capture setup during restore replay."""
return _AUTO_CAPTURE_SUPPRESSED.get()
def auto_capture(scope_type, scope_id, action, label=None, actor=None,
server_id=None):
"""Best-effort pre-mutation capture for use at M2 mutation doors."""
if _AUTO_CAPTURE_SUPPRESSED.get():
return None
action = str(action or 'mutation')
if '.' not in action:
action = f'{scope_type}.{action}'
return capture(
scope_type,
scope_id,
'pre_mutation',
label=label or f'before {action}',
actor=actor,
server_id=server_id,
)
@contextmanager
def suppress_auto_capture():
"""Suppress nested door hooks in this context, resetting even on error."""
token = _AUTO_CAPTURE_SUPPRESSED.set(True)
try:
yield
finally:
_AUTO_CAPTURE_SUPPRESSED.reset(token)
def canonical_json(payload):
"""Match the proven DeploymentSnapshot canonical JSON construction."""
return json.dumps(
payload, sort_keys=True, separators=(',', ':'), default=str,
)
def payload_hash(payload):
return hashlib.sha256(canonical_json(payload).encode('utf-8')).hexdigest()
def _actor_id(actor):
if actor is None:
return None
return getattr(actor, 'id', actor)
def _adapter_coverage(adapter, scope_type, scope_id, server_id):
coverage = [BASE_COVERAGE]
coverage.extend(SCOPE_COVERAGE.get(scope_type, ()))
extra = _member(adapter, 'coverage')
if callable(extra):
extra = extra(scope_id, server_id=server_id)
if isinstance(extra, str):
extra = [extra]
for statement in extra or ():
if statement and statement not in coverage:
coverage.append(statement)
return coverage
def _retention_days():
from app.services.settings_service import SettingsService
value = SettingsService.get(
'restore_point_retention_days', DEFAULT_RETENTION_DAYS,
)
try:
return max(0, int(value))
except (TypeError, ValueError):
return DEFAULT_RETENTION_DAYS
def _capture_payload(adapter, scope_id, server_id):
return _member(adapter, 'capture')(scope_id, server_id=server_id)
def _session_has_pending_changes():
"""Whether capture would accidentally own another service's unit of work."""
session = db.session()
return bool(session.new or session.dirty or session.deleted)
def _audit_capture(point):
from app.models.audit_log import AuditLog
from app.services.audit_service import AuditService
AuditService.log(
AuditLog.ACTION_RESTORE_POINT_CREATE,
user_id=point.actor_user_id,
target_type='restore_point',
target_id=None,
details={
'restore_point_id': point.id,
'server_id': point.server_id,
'scope_type': point.scope_type,
'scope_id': point.scope_id,
'trigger': point.trigger,
'label': point.label,
},
commit=False,
)
def capture(scope_type, scope_id, trigger, label=None, actor=None,
server_id=None):
"""Capture and dedupe one scope, returning a row or ``None`` on failure."""
from app.models.restore_point import RestorePoint
scope_type = str(scope_type or '')
scope_id = str(scope_id or '')
adapter = get_adapter(scope_type)
if not scope_type or not scope_id or adapter is None:
logger.warning(
'Restore-point capture skipped for %s/%s: adapter not registered',
scope_type or '?', scope_id or '?',
)
return None
# capture() commits its point + audit atomically. Never let that commit (or
# its failure rollback) absorb a caller's pending unit of work.
if _session_has_pending_changes():
logger.warning(
'Restore-point capture skipped for %s/%s: caller transaction '
'has pending changes', scope_type, scope_id,
)
return None
owns_transaction = False
try:
payload = _capture_payload(adapter, scope_id, server_id)
# Adapters are read-only during capture. If one dirtied the session,
# leave its objects untouched for the caller and refuse the checkpoint.
if _session_has_pending_changes():
logger.warning(
'Restore-point capture skipped for %s/%s: adapter left '
'pending database changes', scope_type, scope_id,
)
return None
owns_transaction = True
if not isinstance(payload, dict):
raise ValueError('restore-point adapter capture must return a mapping')
canonical = canonical_json(payload)
digest = hashlib.sha256(canonical.encode('utf-8')).hexdigest()
latest = RestorePoint.latest_for_scope(
scope_type, scope_id, server_id=server_id,
)
if latest and latest.payload_hash == digest:
# A manual quicksave doubles as a retained tag. Dedupe must not
# throw away that operator intent just because an automatic point
# already captured the same bytes.
if str(trigger) == 'manual':
now = datetime.utcnow()
latest.keep = True
latest.trigger = 'manual'
latest.actor_user_id = _actor_id(actor)
if label and latest.label != str(label)[:255]:
latest.label = str(label)[:255]
latest.created_at = now
latest.updated_at = now
_audit_capture(latest)
db.session.commit()
return latest
now = datetime.utcnow()
point = RestorePoint(
server_id=server_id,
scope_type=scope_type,
scope_id=scope_id,
trigger=str(trigger),
label=str(label)[:255] if label else None,
payload_hash=digest,
payload_json=canonical,
coverage_json=canonical_json(_adapter_coverage(
adapter, scope_type, scope_id, server_id,
)),
actor_user_id=_actor_id(actor),
expires_at=now + timedelta(days=_retention_days()),
keep=str(trigger) == 'manual',
)
db.session.add(point)
db.session.flush() # uuid/defaults are available to the audit details
_audit_capture(point)
db.session.commit()
return point
except Exception as exc: # noqa: BLE001 -- must never block the mutation
# Before the clean post-adapter boundary, rollback could destroy work
# the caller/adapter still owns. Once the boundary passes, every write
# in this transaction belongs to restore-point capture.
if owns_transaction:
try:
db.session.rollback()
except Exception: # pragma: no cover - defensive
pass
logger.warning(
'Restore-point capture failed for %s/%s: %s',
scope_type, scope_id, exc, exc_info=True,
)
return None
def _point_or_raise(point_id):
from app.models.restore_point import RestorePoint
point = db.session.get(RestorePoint, point_id)
if point is None:
raise RestorePointNotFoundError(f'Restore point {point_id} not found')
return point
def get(point_id):
"""Return one restore point or raise the public typed 404."""
return _point_or_raise(point_id)
_FILTER_UNSET = object()
def list_points(scope_type=None, scope_id=None, server_id=_FILTER_UNSET,
limit=50, allowed_application_scope_ids=None,
include_operational=True):
"""List restore points without leaking ORM work into the API boundary.
``allowed_application_scope_ids`` applies the grant-aware application
portion of the union *before* limit/order. ``None`` means every app scope
(admin); an empty iterable means no app scopes. Operational rows are an
independent branch controlled by ``include_operational``.
"""
from app.models.restore_point import RestorePoint
query = RestorePoint.query
if scope_type is not None:
query = query.filter(RestorePoint.scope_type == str(scope_type))
if scope_id is not None:
query = query.filter(RestorePoint.scope_id == str(scope_id))
if server_id is not _FILTER_UNSET:
query = query.filter(RestorePoint.server_id == server_id)
app_types = ('application', 'env')
authorized = []
if include_operational:
authorized.append(RestorePoint.scope_type.notin_(app_types))
if allowed_application_scope_ids is None:
authorized.append(RestorePoint.scope_type.in_(app_types))
else:
allowed_ids = tuple(
str(value) for value in allowed_application_scope_ids
)
if allowed_ids:
authorized.append(and_(
RestorePoint.scope_type.in_(app_types),
RestorePoint.scope_id.in_(allowed_ids),
))
query = query.filter(or_(*authorized) if authorized else False)
return (query.order_by(
RestorePoint.created_at.desc(), RestorePoint.id.desc(),
).limit(int(limit)).all())
def accessible_application_scope_ids(user):
"""Application ids visible through the exact ResourceGrant seam."""
if user is None:
return set()
from app.models.application import Application
from app.services.workspace_service import WorkspaceService
query = WorkspaceService.scope_query(
Application.query_active(), Application, user,
owner_attr='user_id', grant_resource_type='application',
)
return {
str(application_id)
for application_id, in query.with_entities(Application.id).all()
}
def resolve_application_scope(scope_type, scope_id):
"""Resolve an app-owned scope for ResourceGrant authorization."""
if str(scope_type) not in {'application', 'env'}:
return None
try:
application_id = int(scope_id)
except (TypeError, ValueError) as exc:
raise RestorePointError('Invalid application scope id') from exc
from app.models.application import Application
application = Application.query_active().filter_by(id=application_id).first()
if application is None:
raise RestorePointScopeNotFoundError(
f'Application {application_id} not found',
)
return application
def resolve_server(server_id):
"""Resolve a server filter/target through the service persistence seam."""
if server_id in (None, ''):
return None
from app.models.server import Server
server = db.session.get(Server, str(server_id))
if server is None:
raise RestorePointScopeNotFoundError(
f'Server {server_id} not found',
)
return server
def capture_manual(scope_type, scope_id, label=None, actor=None,
server_id=None):
"""Strict HTTP-facing wrapper around best-effort door capture.
Automatic mutation hooks intentionally tolerate capture failure. A manual
quicksave is the requested operation itself, so failure must be visible to
the caller as a typed error instead of a false-success response.
"""
if get_adapter(scope_type) is None:
raise RestorePointError(
f'Unsupported restore-point scope type: {scope_type}',
)
point = capture(
scope_type, scope_id, 'manual', label=label, actor=actor,
server_id=server_id,
)
if point is None:
raise RestorePointAdapterError(
f'Could not capture restore point for {scope_type}/{scope_id}',
)
return point
def _strict_payload(point):
"""Parse a stored payload without JsonColumnMixin's lossy fallback."""
try:
payload = json.loads(point.payload_json)
except (TypeError, ValueError) as exc:
raise RestorePointCorruptError(
f'Restore point {point.id} has a corrupt payload',
details={'restore_point_id': point.id},
) from exc
if not isinstance(payload, dict):
raise RestorePointCorruptError(
f'Restore point {point.id} has a corrupt payload',
details={'restore_point_id': point.id},
)
return payload
def _previous_point(point):
from app.models.restore_point import RestorePoint
earlier = or_(
RestorePoint.created_at < point.created_at,
and_(
RestorePoint.created_at == point.created_at,
RestorePoint.id < point.id,
),
)
return (RestorePoint.query.filter_by(
server_id=point.server_id,
scope_type=point.scope_type,
scope_id=point.scope_id,
).filter(earlier)
.order_by(RestorePoint.created_at.desc(), RestorePoint.id.desc())
.first())
def diff_payloads(old, new):
"""Generic secret-safe diff over already-masked checkpoint payloads."""
if isinstance(old, dict) and isinstance(new, dict):
old_keys = set(old)
new_keys = set(new)
return {
'added': {key: new[key] for key in sorted(new_keys - old_keys)},
'removed': {key: old[key] for key in sorted(old_keys - new_keys)},
'changed': {
key: {'old': old[key], 'new': new[key]}
for key in sorted(old_keys & new_keys)
if old[key] != new[key]
},
}
if isinstance(old, list) and isinstance(new, list):
old_by_json = {canonical_json(value): value for value in old}
new_by_json = {canonical_json(value): value for value in new}
return {
'added': [new_by_json[key] for key in sorted(new_by_json.keys() - old_by_json.keys())],
'removed': [old_by_json[key] for key in sorted(old_by_json.keys() - new_by_json.keys())],
'changed': [],
}
return {
'added': [],
'removed': [],
'changed': {'old': old, 'new': new} if old != new else {},
}
def _build_diff(scope_type, old, new):
adapter = get_adapter(scope_type)
adapter_diff = _member(adapter, 'diff') if adapter is not None else None
if not callable(adapter_diff):
return diff_payloads(old, new)
try:
return adapter_diff(old, new)
except RestorePointAdapterError:
raise
except Exception as exc:
raise RestorePointAdapterError(
f'{scope_type} restore-point diff failed: {exc}',
) from exc
def diff(point_id, against='previous'):
"""Diff a point against the previous point or an explicit point id."""
point = _point_or_raise(point_id)
if against in (None, '', 'previous'):
against_point = _previous_point(point)
else:
against_point = _point_or_raise(against)
if (
against_point.server_id != point.server_id
or against_point.scope_type != point.scope_type
or against_point.scope_id != point.scope_id
):
raise RestorePointError('Restore points belong to different scopes')
old = _strict_payload(against_point) if against_point else {}
new = _strict_payload(point)
return {
'point_id': point.id,
'against_point_id': against_point.id if against_point else None,
'diff': _build_diff(point.scope_type, old, new),
'has_changes': canonical_json(old) != canonical_json(new),
}
def _normalize_refusals(value):
if value in (None, True):
return []
if value is False:
return ['The surface safety check refused this restore.']
if isinstance(value, dict):
if value.get('allowed', True) is False:
value = value.get('refusals') or value.get('error') or value
else:
value = value.get('refusals', [])
if isinstance(value, (str, bytes)):
return [value.decode() if isinstance(value, bytes) else value]
if isinstance(value, (list, tuple)):
return list(value)
return [value]
def _restore_refusals(adapter, point, target_payload, current_payload, actor):
validator = _member(adapter, 'validate_restore')
if not callable(validator):
return []
return _normalize_refusals(validator(
point.scope_id,
target_payload,
current_payload,
actor=actor,
server_id=point.server_id,
))
def preview(point_id, actor=None):
"""Read-only current → checkpoint diff, coverage, and safety refusals."""
point = _point_or_raise(point_id)
adapter = get_adapter(point.scope_type)
if adapter is None:
raise RestorePointAdapterError(
f'No restore-point adapter registered for {point.scope_type}',
)
# Validate stored bytes before invoking any adapter code. A corrupt point
# must be inert: no current-state reads, safety probes, diffs, or restores.
target = _strict_payload(point)
try:
current = _capture_payload(adapter, point.scope_id, point.server_id)
refusals = _restore_refusals(adapter, point, target, current, actor)
except ApplicationError:
raise
except Exception as exc:
raise RestorePointAdapterError(str(exc)) from exc
return {
'point_id': point.id,
'scope_type': point.scope_type,
'scope_id': point.scope_id,
'diff': _build_diff(point.scope_type, current, target),
'has_changes': canonical_json(current) != canonical_json(target),
'outside_checkpoint': point.get_coverage(),
'refusals': refusals,
'can_restore': not refusals,
}
def restore(point_id, actor=None):
"""Re-converge through the adapter after a recoverable pre-checkpoint."""
point = _point_or_raise(point_id)
adapter = get_adapter(point.scope_type)
if adapter is None:
raise RestorePointAdapterError(
f'No restore-point adapter registered for {point.scope_type}',
)
target = _strict_payload(point)
restore_preview = preview(point.id, actor=actor)
if restore_preview['refusals']:
raise RestorePointRefusedError(restore_preview['refusals'])
before = capture(
point.scope_type,
point.scope_id,
'pre_mutation',
label=f'before restore {point.id}',
actor=actor,
server_id=point.server_id,
)
if before is None:
raise RestorePointAdapterError(
'Restore aborted because the pre-restore checkpoint could not be captured',
)
try:
with suppress_auto_capture():
result = _member(adapter, 'restore')(
point.scope_id,
target,
actor=actor,
server_id=point.server_id,
)
except ApplicationError:
raise
except Exception as exc:
raise RestorePointAdapterError(str(exc)) from exc
if isinstance(result, dict) and result.get('success') is False:
return result
from app.models.audit_log import AuditLog
from app.services.audit_service import AuditService
AuditService.log(
AuditLog.ACTION_RESTORE_POINT_RESTORE,
user_id=_actor_id(actor),
target_type='restore_point',
target_id=None,
details={
'restore_point_id': point.id,
'pre_restore_point_id': before.id if before else None,
'server_id': point.server_id,
'scope_type': point.scope_type,
'scope_id': point.scope_id,
},
)
return result if result is not None else {'success': True}
def prune(retention_days=DEFAULT_RETENTION_DAYS, per_scope_cap=DEFAULT_SCOPE_CAP,
now=None):
"""Expire old unkept rows and cap each server/scope timeline at 50."""
from app.models.restore_point import RestorePoint
try:
retention_days = max(0, int(retention_days))
except (TypeError, ValueError):
retention_days = DEFAULT_RETENTION_DAYS
try:
per_scope_cap = max(0, int(per_scope_cap))
except (TypeError, ValueError):
per_scope_cap = DEFAULT_SCOPE_CAP
now = now or datetime.utcnow()
backfilled = 0
expired_deleted = 0
cap_deleted = 0
try:
pending = RestorePoint.query.filter(
RestorePoint.keep.is_(False),
RestorePoint.expires_at.is_(None),
).all()
for point in pending:
point.expires_at = (point.created_at or now) + timedelta(
days=retention_days,
)
backfilled += 1
expired = RestorePoint.query.filter(
RestorePoint.keep.is_(False),
RestorePoint.expires_at.isnot(None),
RestorePoint.expires_at <= now,
).all()
for point in expired:
db.session.delete(point)
expired_deleted += 1
db.session.flush()
scopes = db.session.query(
RestorePoint.server_id,
RestorePoint.scope_type,
RestorePoint.scope_id,
).filter(RestorePoint.keep.is_(False)).distinct().all()
for server_id, scope_type, scope_id in scopes:
rows = (RestorePoint.query.filter_by(
server_id=server_id,
scope_type=scope_type,
scope_id=scope_id,
keep=False,
).order_by(RestorePoint.created_at.desc(), RestorePoint.id.desc())
.all())
for point in rows[per_scope_cap:]:
db.session.delete(point)
cap_deleted += 1
db.session.commit()
return {
'success': True,
'backfilled': backfilled,
'expired_deleted': expired_deleted,
'cap_deleted': cap_deleted,
'deleted': expired_deleted + cap_deleted,
}
except Exception as exc: # noqa: BLE001 -- scheduled job reports cleanly
db.session.rollback()
logger.error('Restore-point retention failed: %s', exc, exc_info=True)
return {
'success': False,
'error': str(exc),
'backfilled': backfilled,
'expired_deleted': expired_deleted,
'cap_deleted': cap_deleted,
'deleted': expired_deleted + cap_deleted,
}
class RestorePointService:
"""Class facade matching other ServerKit service modules."""
capture = staticmethod(capture)
capture_manual = staticmethod(capture_manual)
get = staticmethod(get)
list_points = staticmethod(list_points)
diff = staticmethod(diff)
preview = staticmethod(preview)
restore = staticmethod(restore)
prune = staticmethod(prune)
register_adapter = staticmethod(register_adapter)
auto_capture = staticmethod(auto_capture)
auto_capture_is_suppressed = staticmethod(auto_capture_is_suppressed)
suppress_auto_capture = staticmethod(suppress_auto_capture)