Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(backups): backup protection backend — policy, scheduler, smart backups, API

Juan Denis1c641b2a9dd5
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 1ec09286..89a5e7f8 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -450,6 +450,8 @@ def create_app(config_name=None):
WorkflowEngine.register_jobs()
from app.services.backup_service import BackupService
BackupService.register_jobs()
+ from app.services.backup_policy_service import BackupPolicyService
+ BackupPolicyService.register_jobs()
start_job_system(app, seed=seed_builtin_schedules)
# Request body size limit
diff --git a/backend/app/api/apps.py b/backend/app/api/apps.py
index 695f6399..9959def8 100644
--- a/backend/app/api/apps.py
+++ b/backend/app/api/apps.py
@@ -19,6 +19,7 @@ from app.services.container_sleep_service import ContainerSleepService
from app.services.container_scale_service import ContainerScaleService
from app.services.log_service import LogService
from app.services.process_service import ProcessService
+from app.services.backup_policy_service import BackupPolicyService, BackupPolicyError
from app.services.upload_service import (
ensure_app_dirs,
validate_zip,
@@ -1698,3 +1699,114 @@ def get_app_status(app_id):
'port': app.port,
'port_accessible': port_status.get('accessible') if port_status else None
}), 200
+
+
+# ==================== BACKUP PROTECTION (policy + runs) ====================
+
+def _load_app_for_backup(app_id, edit=False):
+ """Load an app the current user may access (or edit). Returns (app, error)."""
+ user = User.query.get(get_jwt_identity())
+ app = Application.query.get(app_id)
+ if not app:
+ return None, (jsonify({'error': 'Application not found'}), 404)
+ allowed = _can_edit_app(user, app) if edit else _can_access_app(user, app)
+ if not allowed:
+ return None, (jsonify({'error': 'Access denied'}), 403)
+ return app, None
+
+
+@apps_bp.route('/<int:app_id>/backup-policy', methods=['GET'])
+@jwt_required()
+def get_app_backup_policy(app_id):
+ """Return the protection policy + status for an app (creating a default)."""
+ app, err = _load_app_for_backup(app_id)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ return jsonify(BackupPolicyService.serialize_policy_view(policy))
+
+
+@apps_bp.route('/<int:app_id>/backup-policy', methods=['PUT'])
+@jwt_required()
+def update_app_backup_policy(app_id):
+ """Update the protection policy and re-sync its schedule."""
+ app, err = _load_app_for_backup(app_id, edit=True)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ try:
+ BackupPolicyService.update_policy(policy, request.get_json() or {})
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify(BackupPolicyService.serialize_policy_view(policy))
+
+
+@apps_bp.route('/<int:app_id>/backups', methods=['POST'])
+@jwt_required()
+def trigger_app_backup(app_id):
+ """Enqueue a one-off backup for the app."""
+ app, err = _load_app_for_backup(app_id, edit=True)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ try:
+ job = BackupPolicyService.run_policy_now(policy, manual=True)
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 409
+ return jsonify({'success': True, 'job_id': job.id}), 202
+
+
+@apps_bp.route('/<int:app_id>/backups', methods=['GET'])
+@jwt_required()
+def list_app_backups(app_id):
+ """List backup runs for the app."""
+ app, err = _load_app_for_backup(app_id)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ return jsonify({'runs': BackupPolicyService.list_runs(policy)})
+
+
+@apps_bp.route('/<int:app_id>/backups/<int:run_id>/restore', methods=['POST'])
+@jwt_required()
+def restore_app_backup(app_id, run_id):
+ """Enqueue a restore from a specific backup run."""
+ app, err = _load_app_for_backup(app_id, edit=True)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ try:
+ job = BackupPolicyService.request_restore(policy, run_id, request.get_json() or {})
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify({'success': True, 'job_id': job.id}), 202
+
+
+@apps_bp.route('/<int:app_id>/backups/<int:run_id>/verify', methods=['POST'])
+@jwt_required()
+def verify_app_backup(app_id, run_id):
+ """Verify the remote copy of a backup run."""
+ app, err = _load_app_for_backup(app_id, edit=True)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ try:
+ result = BackupPolicyService.verify_run(policy, run_id)
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify(result)
+
+
+@apps_bp.route('/<int:app_id>/backups/<int:run_id>', methods=['DELETE'])
+@jwt_required()
+def delete_app_backup(app_id, run_id):
+ """Delete a backup run (local + remote + record)."""
+ app, err = _load_app_for_backup(app_id, edit=True)
+ if err:
+ return err
+ policy = BackupPolicyService.get_or_create_policy('application', app_id)
+ try:
+ BackupPolicyService.delete_run(policy, run_id)
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify({'success': True})
diff --git a/backend/app/api/backups.py b/backend/app/api/backups.py
index 0af3da95..2494442e 100644
--- a/backend/app/api/backups.py
+++ b/backend/app/api/backups.py
@@ -5,7 +5,7 @@ from app.middleware.rbac import admin_required
from app.models import Application
from app.services.backup_service import BackupService
from app.services.storage_provider_service import StorageProviderService
-from app import paths
+from app import db, paths
backups_bp = Blueprint('backups', __name__)
@@ -53,6 +53,71 @@ def update_config():
return jsonify(result), 200 if result['success'] else 400
+@backups_bp.route('/cost-rates', methods=['GET'])
+@jwt_required()
+@admin_required
+def get_cost_rates():
+ """Storage-cost rates ($/GB/month). 'local' is the operator's own server
+ disk (free by default); s3/b2 are the real cloud-provider rates."""
+ from app.services.backup_cost_service import BackupCostService, DEFAULT_RATES
+ return jsonify({'rates': BackupCostService.get_rates(), 'defaults': DEFAULT_RATES}), 200
+
+
+@backups_bp.route('/cost-rates', methods=['PUT'])
+@jwt_required()
+@admin_required
+def update_cost_rates():
+ """Update storage-cost rates. Accepts {rates:{local,s3,b2}} or the flat dict."""
+ from app.services.backup_cost_service import BackupCostService
+ data = request.get_json() or {}
+ rates = BackupCostService.save_rates(data.get('rates') if 'rates' in data else data)
+ return jsonify({'success': True, 'rates': rates}), 200
+
+
+@backups_bp.route('/cost-summary', methods=['GET'])
+@jwt_required()
+@admin_required
+def cost_summary():
+ """Aggregate storage cost across all protection backups (BackupRun rows),
+ recomputed from current sizes x current rates, plus a forward projection."""
+ from sqlalchemy import func
+ from app.models.backup_run import BackupRun
+ from app.models.backup_policy import BackupPolicy
+ from app.services.backup_cost_service import BackupCostService
+
+ totals = db.session.query(
+ func.coalesce(func.sum(BackupRun.size_local), 0),
+ func.coalesce(func.sum(BackupRun.size_remote), 0),
+ func.count(BackupRun.id),
+ ).filter(BackupRun.status == 'success').first()
+ size_local = int(totals[0] or 0)
+ size_remote = int(totals[1] or 0)
+ count = int(totals[2] or 0)
+
+ remote_provider = BackupCostService.configured_remote_provider()
+ cost_local = float(BackupCostService.compute_cost(size_local, 'local'))
+ cost_remote = float(BackupCostService.compute_cost(size_remote, remote_provider)) if remote_provider else 0.0
+
+ projected = 0.0
+ for policy in BackupPolicy.query.all():
+ recent = (BackupRun.query.filter_by(policy_id=policy.id, status='success')
+ .order_by(BackupRun.started_at.desc()).limit(5).all())
+ sizes = [r.size_local or 0 for r in recent]
+ avg = (sum(sizes) / len(sizes)) if sizes else (policy.last_size or 0)
+ projected += float(BackupCostService.project_monthly_cost(policy, avg))
+
+ return jsonify({
+ 'backup_count': count,
+ 'total_size_local': size_local,
+ 'total_size_remote': size_remote,
+ 'total_cost_local': round(cost_local, 4),
+ 'total_cost_remote': round(cost_remote, 4),
+ 'total_cost': round(cost_local + cost_remote, 4),
+ 'projected_monthly_cost': round(projected, 4),
+ 'cost_rates': BackupCostService.get_rates(),
+ }), 200
+
+
@backups_bp.route('/application', methods=['POST'])
@jwt_required()
@admin_required
diff --git a/backend/app/api/wordpress_sites.py b/backend/app/api/wordpress_sites.py
index 8c9f2945..bdce0b2d 100644
--- a/backend/app/api/wordpress_sites.py
+++ b/backend/app/api/wordpress_sites.py
@@ -21,6 +21,7 @@ from app.models.wordpress_site import WordPressSite, DatabaseSnapshot
from app.services.wordpress_env_service import WordPressEnvService
from app.services.db_sync_service import DatabaseSyncService
from app.services.git_wordpress_service import GitWordPressService
+from app.services.backup_policy_service import BackupPolicyService, BackupPolicyError
wordpress_sites_bp = Blueprint('wordpress_sites', __name__)
@@ -217,6 +218,109 @@ def delete_snapshot(site_id, snapshot_id):
return jsonify({'success': True, 'message': 'Snapshot deleted'})
+# =============================================================================
+# Backup Protection (policy + runs)
+# =============================================================================
+
+def _load_wp_site(site_id):
+ """Load a site the current user owns, or None."""
+ user = get_current_user()
+ return WordPressSite.query.join(Application).filter(
+ WordPressSite.id == site_id,
+ Application.user_id == user.id,
+ ).first()
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backup-policy', methods=['GET'])
+@auth_required()
+def get_wp_backup_policy(site_id):
+ """Return the protection policy + status for a site (creating a default)."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ return jsonify(BackupPolicyService.serialize_policy_view(policy))
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backup-policy', methods=['PUT'])
+@auth_required()
+def update_wp_backup_policy(site_id):
+ """Update the protection policy and re-sync its schedule."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ try:
+ BackupPolicyService.update_policy(policy, request.get_json() or {})
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify(BackupPolicyService.serialize_policy_view(policy))
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backups', methods=['POST'])
+@auth_required()
+def trigger_wp_backup(site_id):
+ """Enqueue a one-off backup for the site."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ try:
+ job = BackupPolicyService.run_policy_now(policy, manual=True)
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 409
+ return jsonify({'success': True, 'job_id': job.id}), 202
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backups', methods=['GET'])
+@auth_required()
+def list_wp_backups(site_id):
+ """List backup runs for the site."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ return jsonify({'runs': BackupPolicyService.list_runs(policy)})
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backups/<int:run_id>/restore', methods=['POST'])
+@auth_required()
+def restore_wp_backup(site_id, run_id):
+ """Enqueue a restore from a specific backup run."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ try:
+ job = BackupPolicyService.request_restore(policy, run_id, request.get_json() or {})
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify({'success': True, 'job_id': job.id}), 202
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backups/<int:run_id>/verify', methods=['POST'])
+@auth_required()
+def verify_wp_backup(site_id, run_id):
+ """Verify the remote copy of a backup run."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ try:
+ result = BackupPolicyService.verify_run(policy, run_id)
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify(result)
+
+
+@wordpress_sites_bp.route('/sites/<int:site_id>/backups/<int:run_id>', methods=['DELETE'])
+@auth_required()
+def delete_wp_backup(site_id, run_id):
+ """Delete a backup run (local + remote + record)."""
+ if not _load_wp_site(site_id):
+ return jsonify({'error': 'Site not found'}), 404
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', site_id)
+ try:
+ BackupPolicyService.delete_run(policy, run_id)
+ except BackupPolicyError as e:
+ return jsonify({'error': str(e)}), 400
+ return jsonify({'success': True})
+
+
@wordpress_sites_bp.route('/sites/<int:site_id>/clone-db', methods=['POST'])
@auth_required()
def clone_database(site_id):
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 1dcf364d..2c881cd2 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -44,6 +44,8 @@ from app.models.passkey import PasskeyCredential
from app.models.secret_vault import SecretVault, Secret
from app.models.webhook_gateway import WebhookEndpoint, WebhookDelivery
from app.models.waf_policy import WafPolicy
+from app.models.backup_policy import BackupPolicy
+from app.models.backup_run import BackupRun
from app.queue_bus.models import QueueGroup, Queue, QueueMessage
from app.notifications.models import Notification, NotificationDelivery
from app.models.email_provider import EmailProviderConnection
@@ -76,6 +78,7 @@ __all__ = [
'SecretVault', 'Secret',
'WebhookEndpoint', 'WebhookDelivery',
'WafPolicy',
+ 'BackupPolicy', 'BackupRun',
'QueueGroup', 'Queue', 'QueueMessage',
'Notification', 'NotificationDelivery',
'EmailProviderConnection',
diff --git a/backend/app/models/backup_policy.py b/backend/app/models/backup_policy.py
new file mode 100644
index 00000000..145cee50
--- /dev/null
+++ b/backend/app/models/backup_policy.py
@@ -0,0 +1,99 @@
+from datetime import datetime
+from decimal import Decimal
+
+from app import db
+
+
+def _num(value):
+ """Serialize a Numeric/Decimal column to a JSON-friendly float (or None)."""
+ if value is None:
+ return None
+ if isinstance(value, Decimal):
+ return float(value)
+ return value
+
+
+class BackupPolicy(db.Model):
+ """Automated backup ("protection") policy for a single target.
+
+ A target is either a WordPress site (``target_type='wordpress_site'``) or a
+ generic application (``target_type='application'``). There is at most one
+ policy per target. The cron schedule is mirrored into a ``ScheduledJob`` row
+ by :class:`BackupPolicyService` so firing happens on the unified job bus.
+
+ The ``last_*`` columns are a denormalized cache of the most recent run so the
+ UI can render the protection status without scanning ``backup_runs``.
+ """
+
+ __tablename__ = 'backup_policies'
+
+ id = db.Column(db.Integer, primary_key=True)
+ target_type = db.Column(db.String(40), nullable=False, index=True) # 'wordpress_site' | 'application'
+ target_id = db.Column(db.Integer, nullable=False, index=True)
+ enabled = db.Column(db.Boolean, default=False, nullable=False)
+
+ # Schedule (cron expression fired by the unified scheduler)
+ schedule_cron = db.Column(db.String(120), default='0 2 * * *', nullable=False)
+
+ # Retention
+ retention_count = db.Column(db.Integer, default=14, nullable=False)
+ retention_days = db.Column(db.Integer, default=30, nullable=False)
+
+ # Smart backup
+ full_every_n_days = db.Column(db.Integer, default=7, nullable=False)
+ compression = db.Column(db.String(20), default='balanced', nullable=False) # 'fast' | 'balanced' | 'max'
+
+ # Remote
+ remote_copy = db.Column(db.Boolean, default=False, nullable=False)
+
+ # Hooks (optional shell snippets run before/after a backup)
+ pre_backup_hook = db.Column(db.Text, nullable=True)
+ post_backup_hook = db.Column(db.Text, nullable=True)
+
+ # Denormalized last-run cache for the UI
+ last_run_at = db.Column(db.DateTime, nullable=True)
+ last_status = db.Column(db.String(20), nullable=True) # 'success' | 'failed' | 'running'
+ last_size = db.Column(db.BigInteger, nullable=True)
+ last_cost_local = db.Column(db.Numeric(10, 4), nullable=True)
+ last_cost_remote = db.Column(db.Numeric(10, 4), nullable=True)
+ last_job_id = db.Column(db.String(36), nullable=True)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+ runs = db.relationship(
+ 'BackupRun',
+ backref='policy',
+ lazy='dynamic',
+ cascade='all, delete-orphan',
+ order_by='BackupRun.started_at.desc()',
+ )
+
+ __table_args__ = (db.UniqueConstraint('target_type', 'target_id', name='uq_backup_policy_target'),)
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'target_type': self.target_type,
+ 'target_id': self.target_id,
+ 'enabled': self.enabled,
+ 'schedule_cron': self.schedule_cron,
+ 'retention_count': self.retention_count,
+ 'retention_days': self.retention_days,
+ 'full_every_n_days': self.full_every_n_days,
+ 'compression': self.compression,
+ 'remote_copy': self.remote_copy,
+ 'pre_backup_hook': self.pre_backup_hook,
+ 'post_backup_hook': self.post_backup_hook,
+ 'last_run_at': self.last_run_at.isoformat() if self.last_run_at else None,
+ 'last_status': self.last_status,
+ 'last_size': self.last_size,
+ 'last_cost_local': _num(self.last_cost_local),
+ 'last_cost_remote': _num(self.last_cost_remote),
+ 'last_job_id': self.last_job_id,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+ }
+
+ def __repr__(self):
+ return f'<BackupPolicy {self.id} {self.target_type}:{self.target_id} enabled={self.enabled}>'
diff --git a/backend/app/models/backup_run.py b/backend/app/models/backup_run.py
new file mode 100644
index 00000000..d302b50a
--- /dev/null
+++ b/backend/app/models/backup_run.py
@@ -0,0 +1,90 @@
+import json
+from datetime import datetime
+from decimal import Decimal
+
+from app import db
+
+
+def _num(value):
+ """Serialize a Numeric/Decimal column to a JSON-friendly float (or None)."""
+ if value is None:
+ return None
+ if isinstance(value, Decimal):
+ return float(value)
+ return value
+
+
+class BackupRun(db.Model):
+ """A single backup execution produced by a :class:`BackupPolicy`.
+
+ This is the source of truth for the Protection panel's history view. Each run
+ records what was produced (size, paths, cost), whether it was a ``full`` or
+ ``incremental`` backup, and links back to the unified job (``job_id``) that
+ ran it so the UI can deep-link into Jobs.
+ """
+
+ __tablename__ = 'backup_runs'
+
+ id = db.Column(db.Integer, primary_key=True)
+ policy_id = db.Column(db.Integer, db.ForeignKey('backup_policies.id'), nullable=False, index=True)
+ job_id = db.Column(db.String(36), nullable=True, index=True)
+
+ kind = db.Column(db.String(20), nullable=False) # 'full' | 'incremental'
+ status = db.Column(db.String(20), nullable=False) # 'running' | 'success' | 'failed' | 'verifying'
+ started_at = db.Column(db.DateTime, default=datetime.utcnow)
+ finished_at = db.Column(db.DateTime, nullable=True)
+ duration_seconds = db.Column(db.Integer, nullable=True)
+
+ size_local = db.Column(db.BigInteger, default=0)
+ size_remote = db.Column(db.BigInteger, default=0)
+ cost_local = db.Column(db.Numeric(10, 4), default=0)
+ cost_remote = db.Column(db.Numeric(10, 4), default=0)
+
+ storage_path = db.Column(db.Text, nullable=True) # local archive directory/path
+ remote_key = db.Column(db.Text, nullable=True)
+ verified = db.Column(db.Boolean, default=False)
+
+ error_message = db.Column(db.Text, nullable=True)
+ metadata_json = db.Column(db.Text, default='{}') # tables, files, compression, etc.
+
+ def get_metadata(self):
+ if not self.metadata_json:
+ return {}
+ try:
+ return json.loads(self.metadata_json)
+ except (json.JSONDecodeError, TypeError):
+ return {}
+
+ def set_metadata(self, value):
+ self.metadata_json = json.dumps(value or {})
+
+ def to_dict(self):
+ meta = self.get_metadata()
+ cost_local = _num(self.cost_local) or 0
+ cost_remote = _num(self.cost_remote) or 0
+ return {
+ 'id': self.id,
+ 'policy_id': self.policy_id,
+ 'job_id': self.job_id,
+ 'kind': self.kind,
+ 'status': self.status,
+ 'started_at': self.started_at.isoformat() if self.started_at else None,
+ 'finished_at': self.finished_at.isoformat() if self.finished_at else None,
+ 'duration_seconds': self.duration_seconds,
+ 'size_local': self.size_local or 0,
+ 'size_remote': self.size_remote or 0,
+ 'size_total': (self.size_local or 0) + (self.size_remote or 0),
+ 'cost_local': cost_local,
+ 'cost_remote': cost_remote,
+ 'cost_total': round(cost_local + cost_remote, 4),
+ 'storage_path': self.storage_path,
+ 'remote_key': self.remote_key,
+ 'verified': self.verified,
+ 'error_message': self.error_message,
+ 'compression': meta.get('compression'),
+ 'tables': meta.get('tables'),
+ 'metadata': meta,
+ }
+
+ def __repr__(self):
+ return f'<BackupRun {self.id} policy={self.policy_id} {self.kind}/{self.status}>'
diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.py
index 73ee2909..10afd30e 100644
--- a/backend/app/notifications/catalog.py
+++ b/backend/app/notifications/catalog.py
@@ -29,6 +29,18 @@ _CATALOG = {
'severity': 'critical',
'category': 'backups',
},
+ 'restore.completed': {
+ 'title': 'Restore completed: {app}',
+ 'template': 'generic',
+ 'severity': 'success',
+ 'category': 'backups',
+ },
+ 'restore.failed': {
+ 'title': 'Restore failed: {app}',
+ 'template': 'generic',
+ 'severity': 'critical',
+ 'category': 'backups',
+ },
# --- security ---
'security.alert': {
'title': 'Security alert: {alert_type}',
diff --git a/backend/app/services/backup_cost_service.py b/backend/app/services/backup_cost_service.py
new file mode 100644
index 00000000..86045db4
--- /dev/null
+++ b/backend/app/services/backup_cost_service.py
@@ -0,0 +1,161 @@
+"""Storage-cost estimation for backups.
+
+Cost rates ($/GB/month) live in the existing backup config (``backups.json``)
+under ``cost_rates``. ``local`` defaults to $0 (operator can set it if they track
+disk cost); ``s3``/``b2`` carry sensible public list-price defaults. All money is
+handled as :class:`~decimal.Decimal` to avoid float drift, and serialized to float
+only at the API boundary.
+"""
+import math
+from decimal import Decimal, ROUND_HALF_UP
+
+GB = 1024 ** 3
+_QUANT = Decimal('0.0001')
+
+DEFAULT_RATES = {
+ 'local': 0.0,
+ 's3': 0.023, # AWS S3 Standard, us-east-1 list price
+ 'b2': 0.006, # Backblaze B2 list price
+}
+
+
+class BackupCostService:
+ """Compute and project backup storage cost."""
+
+ # ---- rates -----------------------------------------------------------
+
+ @classmethod
+ def get_rates(cls):
+ """Return the effective rate table (defaults merged with config)."""
+ rates = dict(DEFAULT_RATES)
+ try:
+ from app.services.backup_service import BackupService
+ for key, value in (BackupService.get_config().get('cost_rates') or {}).items():
+ try:
+ rates[key] = float(value)
+ except (TypeError, ValueError):
+ continue
+ except Exception:
+ pass
+ return rates
+
+ @classmethod
+ def save_rates(cls, rates):
+ """Persist (merge) the provided rate overrides into the backup config."""
+ from app.services.backup_service import BackupService
+ config = BackupService.get_config()
+ merged = dict(DEFAULT_RATES)
+ merged.update(config.get('cost_rates') or {})
+ for key, value in (rates or {}).items():
+ if key not in DEFAULT_RATES:
+ continue
+ try:
+ merged[key] = round(float(value), 6)
+ except (TypeError, ValueError):
+ continue
+ config['cost_rates'] = merged
+ BackupService.save_config(config)
+ return merged
+
+ @classmethod
+ def get_rate(cls, provider):
+ return cls.get_rates().get(provider, DEFAULT_RATES.get(provider, 0.0))
+
+ @classmethod
+ def configured_remote_provider(cls):
+ """Which remote provider is active globally ('s3' | 'b2'), or None."""
+ try:
+ from app.services.storage_provider_service import StorageProviderService
+ provider = (StorageProviderService.get_config() or {}).get('provider', 'local')
+ return provider if provider and provider != 'local' else None
+ except Exception:
+ return None
+
+ # ---- computation -----------------------------------------------------
+
+ @classmethod
+ def compute_cost(cls, size_bytes, provider):
+ """Monthly storage cost (Decimal) for ``size_bytes`` on ``provider``."""
+ rate = cls.get_rate(provider)
+ gigabytes = Decimal(str((size_bytes or 0) / GB))
+ return (gigabytes * Decimal(str(rate))).quantize(_QUANT, rounding=ROUND_HALF_UP)
+
+ @classmethod
+ def format_cost(cls, cost):
+ """Human string like ``$0.04`` / ``$1.20`` / ``$0.0006`` for tiny values."""
+ try:
+ value = float(cost or 0)
+ except (TypeError, ValueError):
+ value = 0.0
+ if value == 0 or value >= 0.01:
+ return f"${value:.2f}"
+ return f"${value:.4f}"
+
+ @classmethod
+ def runs_per_month(cls, cron):
+ """Estimate how many times a cron fires in a 30-day window."""
+ if cron:
+ try:
+ from croniter import croniter
+ from datetime import datetime, timedelta
+ if croniter.is_valid(cron):
+ base = datetime.utcnow()
+ end = base + timedelta(days=30)
+ itr = croniter(cron, base)
+ count = 0
+ while count < 2000:
+ nxt = itr.get_next(datetime)
+ if nxt > end:
+ break
+ count += 1
+ return count or 1
+ except Exception:
+ pass
+ # Heuristic fallback: parse day-of-week / day-of-month fields.
+ try:
+ fields = (cron or '0 2 * * *').split()
+ dow = fields[4] if len(fields) >= 5 else '*'
+ if dow not in ('*', '?'):
+ days = cls._count_dow(dow)
+ return max(1, round(days * 30 / 7))
+ except Exception:
+ pass
+ return 30 # assume daily
+
+ @staticmethod
+ def _count_dow(dow_field):
+ seen = set()
+ for part in dow_field.split(','):
+ if '-' in part:
+ try:
+ lo, hi = part.split('-')
+ for d in range(int(lo), int(hi) + 1):
+ seen.add(d % 7)
+ except ValueError:
+ continue
+ else:
+ try:
+ seen.add(int(part) % 7)
+ except ValueError:
+ continue
+ return len(seen) or 1
+
+ @classmethod
+ def expected_retained_count(cls, policy):
+ """How many backups a policy keeps in steady state (count ∧ days rules)."""
+ per_month = cls.runs_per_month(policy.schedule_cron)
+ per_day = per_month / 30.0
+ by_days = math.ceil(per_day * (policy.retention_days or 1))
+ return max(1, min(policy.retention_count or 1, by_days or 1))
+
+ @classmethod
+ def project_monthly_cost(cls, policy, avg_size):
+ """Estimated monthly storage cost for one policy at ``avg_size`` per run."""
+ retained = cls.expected_retained_count(policy)
+ stored = (avg_size or 0) * retained
+ cost = cls.compute_cost(stored, 'local')
+ if policy.remote_copy:
+ provider = cls.configured_remote_provider()
+ if provider:
+ cost += cls.compute_cost(stored, provider)
+ return cost.quantize(_QUANT, rounding=ROUND_HALF_UP)
diff --git a/backend/app/services/backup_policy_service.py b/backend/app/services/backup_policy_service.py
new file mode 100644
index 00000000..788d28c6
--- /dev/null
+++ b/backend/app/services/backup_policy_service.py
@@ -0,0 +1,800 @@
+"""Backup "protection" policy service.
+
+Owns the lifecycle of a :class:`BackupPolicy`: CRUD, mirroring the cron schedule
+into a ``ScheduledJob`` on the unified job bus, enqueuing one-off runs, and the
+job handlers that actually produce :class:`BackupRun` records.
+
+Job kinds (intentionally distinct from the legacy ``backup.run`` config-schedule
+handler so the two systems coexist):
+ * ``backup.policy.run`` — run a policy's backup once.
+ * ``restore.run`` — restore a target from a specific BackupRun.
+"""
+import logging
+import os
+import shutil
+from datetime import datetime, timedelta
+from decimal import Decimal
+
+from app import db
+from app.utils.formatting import format_bytes
+
+logger = logging.getLogger(__name__)
+
+BACKUP_POLICY_JOB_KIND = 'backup.policy.run'
+RESTORE_JOB_KIND = 'restore.run'
+
+VALID_COMPRESSION = ('fast', 'balanced', 'max')
+# A 'running' run older than this is treated as crashed, not in-flight.
+STALE_RUN_AFTER = timedelta(hours=6)
+
+
+class BackupPolicyError(ValueError):
+ """Raised for invalid policy input or rejected operations (maps to HTTP 400)."""
+
+
+class BackupPolicyService:
+
+ # ------------------------------------------------------------------ #
+ # Policy CRUD
+ # ------------------------------------------------------------------ #
+
+ @staticmethod
+ def _job_name(policy):
+ return f'backup.{policy.target_type}.{policy.target_id}'
+
+ @classmethod
+ def get_policy(cls, target_type, target_id):
+ from app.models.backup_policy import BackupPolicy
+ return BackupPolicy.query.filter_by(
+ target_type=target_type, target_id=int(target_id)
+ ).first()
+
+ @classmethod
+ def get_or_create_policy(cls, target_type, target_id):
+ from app.models.backup_policy import BackupPolicy
+ policy = cls.get_policy(target_type, target_id)
+ if policy:
+ return policy
+ policy = BackupPolicy(target_type=target_type, target_id=int(target_id))
+ db.session.add(policy)
+ db.session.commit()
+ cls.ensure_scheduled_job(policy)
+ return policy
+
+ @classmethod
+ def validate_fields(cls, fields):
+ """Validate a partial update dict; raises BackupPolicyError."""
+ for key in ('retention_count', 'retention_days', 'full_every_n_days'):
+ if key in fields and fields[key] is not None:
+ try:
+ if int(fields[key]) < 1:
+ raise BackupPolicyError(f'{key} must be >= 1')
+ except (TypeError, ValueError):
+ raise BackupPolicyError(f'{key} must be an integer >= 1')
+ if fields.get('compression') is not None and fields['compression'] not in VALID_COMPRESSION:
+ raise BackupPolicyError(f"compression must be one of {VALID_COMPRESSION}")
+ cron = fields.get('schedule_cron')
+ if cron is not None and not cls._cron_valid(cron):
+ raise BackupPolicyError('Invalid cron expression')
+ if fields.get('remote_copy'):
+ from app.services.backup_cost_service import BackupCostService
+ if not BackupCostService.configured_remote_provider():
+ raise BackupPolicyError(
+ 'Remote storage is not configured. Configure it in Backups → Storage first.'
+ )
+
+ @staticmethod
+ def _cron_valid(cron):
+ if not cron or len(cron.split()) < 5:
+ return False
+ try:
+ from croniter import croniter
+ return bool(croniter.is_valid(cron))
+ except ImportError:
+ return True # can't validate without croniter; trust the caller
+
+ # Whitelisted, mutable policy fields.
+ _MUTABLE = (
+ 'enabled', 'schedule_cron', 'retention_count', 'retention_days',
+ 'full_every_n_days', 'compression', 'remote_copy',
+ 'pre_backup_hook', 'post_backup_hook',
+ )
+
+ @classmethod
+ def update_policy(cls, policy, fields):
+ """Apply a partial update, persist, and re-sync the ScheduledJob."""
+ clean = {k: v for k, v in (fields or {}).items() if k in cls._MUTABLE}
+ cls.validate_fields(clean)
+ for key, value in clean.items():
+ if key in ('retention_count', 'retention_days', 'full_every_n_days') and value is not None:
+ value = int(value)
+ setattr(policy, key, value)
+ db.session.commit()
+ cls.ensure_scheduled_job(policy)
+ return policy
+
+ # ------------------------------------------------------------------ #
+ # Scheduled-job wiring
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def ensure_scheduled_job(cls, policy):
+ """Upsert the ScheduledJob row mirroring this policy's cron + enabled."""
+ from app.jobs.service import ScheduledJobService
+ from app.jobs.models import ScheduledJob
+ name = cls._job_name(policy)
+ ScheduledJobService.ensure(
+ name=name,
+ kind=BACKUP_POLICY_JOB_KIND,
+ cron=policy.schedule_cron,
+ payload={'policy_id': policy.id},
+ max_attempts=1, # backups aren't idempotent — no auto-retry
+ enabled=policy.enabled,
+ )
+ # ensure() preserves the existing enabled flag on update, so push the
+ # policy's current toggle explicitly.
+ scheduled = ScheduledJob.query.filter_by(name=name).first()
+ if scheduled and scheduled.enabled != policy.enabled:
+ ScheduledJobService.set_enabled(scheduled.id, policy.enabled)
+ return scheduled
+
+ @classmethod
+ def _scheduled_job(cls, policy):
+ from app.jobs.models import ScheduledJob
+ return ScheduledJob.query.filter_by(name=cls._job_name(policy)).first()
+
+ # ------------------------------------------------------------------ #
+ # Manual trigger + concurrency
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def is_running(cls, policy):
+ from app.models.backup_run import BackupRun
+ cutoff = datetime.utcnow() - STALE_RUN_AFTER
+ return db.session.query(BackupRun.id).filter(
+ BackupRun.policy_id == policy.id,
+ BackupRun.status.in_(('running', 'verifying')),
+ BackupRun.started_at >= cutoff,
+ ).first() is not None
+
+ @classmethod
+ def run_policy_now(cls, policy, manual=True):
+ """Enqueue a one-off backup.policy.run job; rejects if one is in flight."""
+ from app.jobs.service import JobService
+ if cls.is_running(policy):
+ raise BackupPolicyError('A backup is already in progress.')
+ job = JobService.enqueue(
+ BACKUP_POLICY_JOB_KIND,
+ payload={'policy_id': policy.id, 'manual': bool(manual)},
+ max_attempts=1,
+ owner_type='backup_policy',
+ owner_id=policy.id,
+ )
+ return job
+
+ # ------------------------------------------------------------------ #
+ # Target resolution
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def _resolve_target(cls, policy):
+ """Return a dict describing the live target, or raise if missing.
+
+ keys: name, root_path, target_type, site (wp only), app, db_config (wp).
+ """
+ if policy.target_type == 'wordpress_site':
+ from app.models.wordpress_site import WordPressSite
+ site = WordPressSite.query.get(policy.target_id)
+ if not site:
+ raise BackupPolicyError('WordPress site not found')
+ app = site.application
+ if not app or not app.root_path:
+ raise BackupPolicyError('Target path not found')
+ return {
+ 'name': app.name, 'root_path': app.root_path,
+ 'target_type': 'wordpress_site', 'site': site, 'app': app,
+ }
+ # application
+ from app.models.application import Application
+ app = Application.query.get(policy.target_id)
+ if not app:
+ raise BackupPolicyError('Application not found')
+ if not app.root_path:
+ raise BackupPolicyError('Target path not found')
+ return {
+ 'name': app.name, 'root_path': app.root_path,
+ 'target_type': 'application', 'site': None, 'app': app,
+ }
+
+ # ------------------------------------------------------------------ #
+ # Backup execution (Phase 1: full backups; Phase 3 adds incremental)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def _run_hook(cls, hook, label, target):
+ """Run an optional pre/post shell hook; raise on non-zero exit."""
+ if not hook or not hook.strip():
+ return
+ import subprocess
+ env = dict(os.environ)
+ env['SERVERKIT_TARGET_NAME'] = target['name']
+ env['SERVERKIT_TARGET_PATH'] = target['root_path'] or ''
+ try:
+ result = subprocess.run(
+ hook, shell=True, cwd=target['root_path'] or None, env=env,
+ capture_output=True, text=True, timeout=600,
+ )
+ except Exception as exc:
+ raise BackupPolicyError(f'{label} hook error: {exc}')
+ if result.returncode != 0:
+ raise BackupPolicyError(
+ f'{label} hook failed (exit {result.returncode}): '
+ f'{(result.stderr or result.stdout or "").strip()[:300]}'
+ )
+
+ @classmethod
+ def _policy_dir(cls, policy):
+ from app.services.backup_service import BackupService
+ return os.path.join(BackupService.BACKUP_BASE_DIR, 'policies', str(policy.id))
+
+ @classmethod
+ def _snar_path(cls, policy):
+ return os.path.join(cls._policy_dir(policy), 'incremental.snar')
+
+ @classmethod
+ def _decide_kind(cls, policy):
+ """Choose full vs incremental for the next run. WordPress is always full
+ (files + db via wp-cli); applications use the snar-based tar chain: full
+ on first run / missing snar / when a full is due, else incremental."""
+ from app.models.backup_run import BackupRun
+ if policy.target_type != 'application':
+ return 'full'
+ if not os.path.exists(cls._snar_path(policy)):
+ return 'full'
+ last_full = (BackupRun.query
+ .filter_by(policy_id=policy.id, status='success', kind='full')
+ .order_by(BackupRun.started_at.desc()).first())
+ if not last_full:
+ return 'full'
+ days_since_full = (datetime.utcnow() - (last_full.started_at or datetime.utcnow())).days
+ if days_since_full >= (policy.full_every_n_days or 7):
+ return 'full'
+ return 'incremental'
+
+ @classmethod
+ def _execute_backup(cls, policy, target, kind):
+ """Produce a backup for the target. Returns (storage_path, size, metadata).
+ The actual kind used is metadata['kind'] (a tar fallback can downgrade an
+ incremental to a full). Raises on failure."""
+ meta = {'engine': target['target_type']}
+ if target['target_type'] == 'wordpress_site':
+ from app.services.wordpress_service import WordPressService
+ result = WordPressService.backup_wordpress(target['root_path'], include_db=True)
+ if not result.get('success'):
+ raise BackupPolicyError(result.get('error') or 'WordPress backup failed')
+ storage_path = result.get('backup_path')
+ size = result.get('size') or cls._path_size(storage_path)
+ meta.update({
+ 'kind': 'full', 'compression': 'gzip', 'incremental': False,
+ 'backup_name': result.get('backup_name'), 'includes': ['files', 'database'],
+ 'primary_archive': os.path.join(storage_path, 'files.tar.gz'),
+ })
+ return storage_path, size, meta
+
+ # application — smart incremental + compression tiering
+ from app.models.backup_run import BackupRun
+ from app.services.backup_service import BackupService
+ ts = datetime.utcnow().strftime('%Y%m%d_%H%M%S')
+ run_dir = os.path.join(cls._policy_dir(policy), ts)
+ res = BackupService.smart_backup_files(
+ target['root_path'], run_dir, kind, policy.compression, cls._snar_path(policy),
+ )
+ meta.update({
+ 'kind': res['kind'], 'compression': res['compression'],
+ 'incremental': res.get('incremental', False), 'includes': ['files'],
+ 'backup_name': f"{target['name']}_{ts}_{res['kind']}",
+ 'primary_archive': res['archive'],
+ })
+ if res['kind'] == 'incremental':
+ last_full = (BackupRun.query
+ .filter_by(policy_id=policy.id, status='success', kind='full')
+ .order_by(BackupRun.started_at.desc()).first())
+ meta['full_run_id'] = last_full.id if last_full else None
+ return run_dir, res['size'], meta
+
+ @classmethod
+ def _upload_run(cls, policy, run, meta):
+ """Upload a run's local files to remote storage and verify the primary
+ archive. Mutates run.size_remote/cost_remote/remote_key/verified + meta."""
+ from app.services.storage_provider_service import StorageProviderService
+ from app.services.backup_cost_service import BackupCostService
+ provider = BackupCostService.configured_remote_provider()
+ run_dir = run.storage_path
+ if not provider or not run_dir or not os.path.isdir(run_dir):
+ return
+ prefix = f"policies/{policy.id}/{os.path.basename(run_dir.rstrip('/'))}"
+ primary_local = meta.get('primary_archive')
+ total = 0
+ primary_key = None
+ for root, _dirs, files in os.walk(run_dir):
+ for fname in files:
+ local = os.path.join(root, fname)
+ rel = os.path.relpath(local, run_dir).replace(os.sep, '/')
+ key = f"{prefix}/{rel}"
+ up = StorageProviderService.upload_file(local, key)
+ if not up.get('success'):
+ raise RuntimeError(up.get('error') or f'upload failed: {rel}')
+ total += os.path.getsize(local)
+ if primary_local and os.path.abspath(local) == os.path.abspath(primary_local):
+ primary_key = up.get('remote_key') or key
+ run.size_remote = total
+ run.cost_remote = BackupCostService.compute_cost(total, provider)
+ run.remote_key = primary_key or prefix
+ meta['remote_prefix'] = prefix
+ if primary_local:
+ meta['remote_source'] = primary_local
+ if primary_key and primary_local and os.path.exists(primary_local):
+ try:
+ vr = StorageProviderService.verify_file(primary_key, primary_local)
+ run.verified = bool(vr.get('verified'))
+ except Exception:
+ run.verified = False
+
+ @staticmethod
+ def _path_size(path):
+ if not path or not os.path.exists(path):
+ return 0
+ if os.path.isfile(path):
+ return os.path.getsize(path)
+ total = 0
+ for root, _dirs, files in os.walk(path):
+ for f in files:
+ try:
+ total += os.path.getsize(os.path.join(root, f))
+ except OSError:
+ pass
+ return total
+
+ # ------------------------------------------------------------------ #
+ # Job handler: backup.policy.run
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def run_backup_policy_job(cls, job):
+ from app.models.backup_policy import BackupPolicy
+ from app.models.backup_run import BackupRun
+ from app.services.backup_cost_service import BackupCostService
+
+ payload = job.get_payload() or {}
+ policy = BackupPolicy.query.get(payload.get('policy_id'))
+ if not policy:
+ raise ValueError(f"backup policy {payload.get('policy_id')!r} not found")
+
+ # Don't overlap an in-flight run (e.g. a schedule firing over a manual run).
+ if cls.is_running(policy):
+ logger.info('Skipping backup for policy %s — a run is already in progress', policy.id)
+ return {'skipped': True, 'reason': 'already running'}
+
+ target = cls._resolve_target(policy) # raises -> job fails with a clear message
+ kind = cls._decide_kind(policy)
+
+ run = BackupRun(policy_id=policy.id, job_id=job.id, kind=kind,
+ status='running', started_at=datetime.utcnow())
+ db.session.add(run)
+ db.session.commit()
+ run_id = run.id
+ started = run.started_at
+
+ try:
+ cls._run_hook(policy.pre_backup_hook, 'pre-backup', target)
+ storage_path, size, meta = cls._execute_backup(policy, target, kind)
+ cls._run_hook(policy.post_backup_hook, 'post-backup', target)
+
+ run = BackupRun.query.get(run_id)
+ run.kind = meta.get('kind', kind) # tar fallback may downgrade incr -> full
+ run.status = 'success'
+ run.finished_at = datetime.utcnow()
+ run.duration_seconds = int((run.finished_at - started).total_seconds())
+ run.size_local = size
+ run.cost_local = BackupCostService.compute_cost(size, 'local')
+ run.storage_path = storage_path
+ run.set_metadata(meta)
+
+ # Remote copy (upload + verify) — best-effort; a remote failure must
+ # not discard the good local backup.
+ if policy.remote_copy:
+ try:
+ cls._upload_run(policy, run, meta)
+ run.set_metadata(meta)
+ except Exception as exc: # noqa: BLE001
+ logger.warning('Remote copy failed for run %s: %s', run_id, exc)
+
+ cls._update_policy_cache(policy.id, run)
+ db.session.commit()
+
+ # Retention cleanup is best-effort and must never fail the backup.
+ try:
+ cls.apply_retention(policy)
+ except Exception as exc: # noqa: BLE001
+ logger.warning('Retention cleanup failed for policy %s: %s', policy.id, exc)
+
+ cls._notify('backup.completed', target['name'], {
+ 'app': target['name'],
+ 'backup_name': meta.get('backup_name'),
+ 'size': format_bytes(size),
+ 'kind': run.kind,
+ })
+ return {'run_id': run_id, 'status': 'success', 'size': size,
+ 'kind': run.kind, 'name': target['name']}
+
+ except Exception as exc: # noqa: BLE001 — record + re-raise so the job fails
+ db.session.rollback()
+ failed = BackupRun.query.get(run_id)
+ if failed:
+ failed.status = 'failed'
+ failed.error_message = str(exc)[:2000]
+ failed.finished_at = datetime.utcnow()
+ failed.duration_seconds = int((failed.finished_at - started).total_seconds())
+ cls._update_policy_cache(policy.id, failed)
+ db.session.commit()
+ cls._notify('backup.failed', target.get('name') if isinstance(target, dict) else None, {
+ 'app': (target.get('name') if isinstance(target, dict) else None) or 'site',
+ 'error_message': str(exc)[:300],
+ })
+ raise
+
+ @classmethod
+ def _update_policy_cache(cls, policy_id, run):
+ from app.models.backup_policy import BackupPolicy
+ policy = BackupPolicy.query.get(policy_id)
+ if not policy:
+ return
+ policy.last_run_at = run.finished_at or run.started_at
+ policy.last_status = run.status
+ policy.last_size = run.size_local
+ policy.last_cost_local = run.cost_local
+ policy.last_cost_remote = run.cost_remote
+ policy.last_job_id = run.job_id
+
+ @classmethod
+ def apply_retention(cls, policy):
+ """Prune backups beyond the policy's count/age limits.
+
+ A successful backup is kept if it is within the last ``retention_count``
+ successes AND newer than ``retention_days``. The most recent successful
+ backup is always kept. Chain ancestors (the full + intervening
+ incrementals) of any kept incremental are also protected, so a kept
+ backup never loses the archives needed to restore it. Failed runs and
+ out-of-window successes are deleted (local + remote + row)."""
+ from app.models.backup_run import BackupRun
+ successes = (BackupRun.query
+ .filter_by(policy_id=policy.id, status='success')
+ .order_by(BackupRun.started_at.desc()).all()) # newest first
+ if not successes:
+ return
+ cutoff = datetime.utcnow() - timedelta(days=policy.retention_days or 30)
+ keep = {successes[0].id} # always keep the most recent successful backup
+ for idx, run in enumerate(successes):
+ within_count = idx < (policy.retention_count or 14)
+ within_days = (run.started_at or datetime.utcnow()) >= cutoff
+ if within_count and within_days:
+ keep.add(run.id)
+
+ # Protect the chain ancestors of every kept incremental.
+ by_id = {r.id: r for r in successes}
+ for run in successes:
+ if run.id not in keep:
+ continue
+ meta = run.get_metadata() or {}
+ if not meta.get('incremental'):
+ continue
+ full = by_id.get(meta.get('full_run_id'))
+ if not full:
+ continue
+ keep.add(full.id)
+ for other in successes:
+ if (other.kind == 'incremental'
+ and other.started_at is not None
+ and full.started_at is not None
+ and full.started_at <= other.started_at <= run.started_at):
+ keep.add(other.id)
+
+ # Delete every terminal run that isn't protected.
+ candidates = (BackupRun.query
+ .filter(BackupRun.policy_id == policy.id,
+ BackupRun.status.in_(('success', 'failed')))
+ .all())
+ for run in candidates:
+ if run.id in keep:
+ continue
+ try:
+ cls.delete_run(policy, run.id)
+ except Exception as exc: # noqa: BLE001
+ logger.warning('retention: failed to delete run %s: %s', run.id, exc)
+
+ # ------------------------------------------------------------------ #
+ # Restore (Phase 1: working full/files/db restore; Phase 4 adds the UI,
+ # selected-table scope, and richer safety options)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def request_restore(cls, policy, run_id, options):
+ from app.jobs.service import JobService
+ from app.models.backup_run import BackupRun
+ run = BackupRun.query.filter_by(id=run_id, policy_id=policy.id).first()
+ if not run:
+ raise BackupPolicyError('Backup not found')
+ if run.status != 'success':
+ raise BackupPolicyError('Only a successful backup can be restored')
+ if cls.is_running(policy):
+ raise BackupPolicyError('A backup or restore is already in progress.')
+ payload = {
+ 'policy_id': policy.id,
+ 'run_id': run_id,
+ 'scope': (options or {}).get('scope', 'full'),
+ 'tables': (options or {}).get('tables') or [],
+ 'safety_backup': bool((options or {}).get('safety_backup', True)),
+ 'copy_permissions': bool((options or {}).get('copy_permissions', False)),
+ 'maintenance_mode': bool((options or {}).get('maintenance_mode', True)),
+ }
+ return JobService.enqueue(
+ RESTORE_JOB_KIND, payload=payload, max_attempts=1,
+ owner_type='backup_policy', owner_id=policy.id,
+ )
+
+ @classmethod
+ def run_restore_job(cls, job):
+ from app.models.backup_policy import BackupPolicy
+ from app.models.backup_run import BackupRun
+
+ payload = job.get_payload() or {}
+ policy = BackupPolicy.query.get(payload.get('policy_id'))
+ if not policy:
+ raise ValueError('backup policy not found')
+ run = BackupRun.query.filter_by(id=payload.get('run_id'), policy_id=policy.id).first()
+ if not run:
+ raise ValueError('backup run not found')
+ target = cls._resolve_target(policy)
+ scope = payload.get('scope', 'full')
+
+ try:
+ # Optional safety snapshot of the current state before overwriting.
+ if payload.get('safety_backup'):
+ try:
+ cls._safety_backup(policy, target)
+ except Exception as exc: # safety backup is best-effort
+ logger.warning('Safety backup before restore failed: %s', exc)
+
+ if target['target_type'] == 'wordpress_site':
+ cls._restore_wordpress(target, run, scope, payload)
+ else:
+ cls._restore_application(policy, target, run, scope)
+
+ cls._notify('restore.completed', target['name'], {
+ 'app': target['name'], 'scope': scope,
+ })
+ return {'status': 'success', 'scope': scope, 'name': target['name']}
+ except Exception as exc: # noqa: BLE001
+ db.session.rollback()
+ cls._notify('restore.failed', target['name'], {
+ 'app': target['name'], 'error_message': str(exc)[:300],
+ })
+ raise
+
+ @classmethod
+ def _safety_backup(cls, policy, target):
+ from app.models.backup_run import BackupRun
+ from app.services.backup_cost_service import BackupCostService
+ run = BackupRun(policy_id=policy.id, kind='full', status='running',
+ started_at=datetime.utcnow())
+ db.session.add(run)
+ db.session.commit()
+ storage_path, size, meta = cls._execute_backup(policy, target, 'full')
+ meta['safety'] = True
+ run.kind = meta.get('kind', 'full')
+ run.status = 'success'
+ run.finished_at = datetime.utcnow()
+ run.duration_seconds = int((run.finished_at - run.started_at).total_seconds())
+ run.size_local = size
+ run.cost_local = BackupCostService.compute_cost(size, 'local')
+ run.storage_path = storage_path
+ run.set_metadata(meta)
+ db.session.commit()
+
+ @classmethod
+ def _restore_wordpress(cls, target, run, scope, payload):
+ """Restore a WordPress backup. 'full' (and 'tables', for now) restores
+ files + database; 'database' imports only the SQL dump; 'files' extracts
+ only the file archive."""
+ from app.services.wordpress_service import WordPressService
+ meta = run.get_metadata() or {}
+ backup_dir = run.storage_path
+ root = target['root_path']
+
+ if scope == 'database':
+ db_sql = os.path.join(backup_dir or '', 'database.sql')
+ if not os.path.exists(db_sql):
+ raise BackupPolicyError('Database dump not found in this backup')
+ result = WordPressService.wp_cli(root, ['db', 'import', db_sql])
+ if not result.get('success'):
+ raise BackupPolicyError(result.get('error') or 'Database restore failed')
+ return
+
+ if scope == 'files':
+ files_archive = os.path.join(backup_dir or '', 'files.tar.gz')
+ if not os.path.exists(files_archive):
+ raise BackupPolicyError('Files archive not found in this backup')
+ import tarfile
+ with tarfile.open(files_archive, 'r:gz') as tar:
+ tar.extractall(os.path.dirname(root.rstrip('/')) or '/', filter='data')
+ return
+
+ # full (or 'tables', approximated as full until per-table is implemented)
+ backup_name = meta.get('backup_name') or (os.path.basename(backup_dir) if backup_dir else None)
+ if not backup_name:
+ raise BackupPolicyError('Backup archive not found')
+ result = WordPressService.restore_backup(backup_name, root)
+ if not result.get('success'):
+ raise BackupPolicyError(result.get('error') or 'Restore failed')
+
+ @classmethod
+ def _chain_archives(cls, policy, run):
+ """Ordered list of local archive paths needed to restore ``run`` — the
+ base full first, then each incremental up to and including ``run``.
+ Raises if any required archive is missing locally."""
+ from app.models.backup_run import BackupRun
+ meta = run.get_metadata() or {}
+ if not meta.get('incremental'):
+ primary = meta.get('primary_archive')
+ if not primary or not os.path.exists(primary):
+ raise BackupPolicyError('Backup archive not found')
+ return [primary]
+ full = BackupRun.query.get(meta.get('full_run_id')) if meta.get('full_run_id') else None
+ if not full:
+ raise BackupPolicyError('Base full backup for this incremental is missing')
+ chain = (BackupRun.query
+ .filter(BackupRun.policy_id == policy.id, BackupRun.status == 'success',
+ BackupRun.started_at >= full.started_at,
+ BackupRun.started_at <= run.started_at)
+ .order_by(BackupRun.started_at.asc()).all())
+ archives = []
+ for r in chain:
+ m = r.get_metadata() or {}
+ if r.id == full.id or m.get('full_run_id') == full.id:
+ path = m.get('primary_archive')
+ if not path or not os.path.exists(path):
+ raise BackupPolicyError(f'Backup archive missing for run {r.id}')
+ archives.append(path)
+ return archives
+
+ @classmethod
+ def _restore_application(cls, policy, target, run, scope):
+ """Restore an application's files by replaying its incremental chain
+ (full + intervening incrementals) over the app root."""
+ from app.services.backup_service import BackupService
+ archives = cls._chain_archives(policy, run)
+ result = BackupService.restore_incremental_chain(archives, target['root_path'])
+ if not result.get('success'):
+ raise BackupPolicyError(result.get('error') or 'Restore failed')
+
+ # ------------------------------------------------------------------ #
+ # Reads for the API
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def list_runs(cls, policy, limit=200):
+ from app.models.backup_run import BackupRun
+ runs = (BackupRun.query.filter_by(policy_id=policy.id)
+ .order_by(BackupRun.started_at.desc()).limit(limit).all())
+ return [r.to_dict() for r in runs]
+
+ @classmethod
+ def get_run(cls, policy, run_id):
+ from app.models.backup_run import BackupRun
+ return BackupRun.query.filter_by(id=run_id, policy_id=policy.id).first()
+
+ @classmethod
+ def verify_run(cls, policy, run_id):
+ """Verify a run's remote copy (size + checksum) and persist the result."""
+ run = cls.get_run(policy, run_id)
+ if not run:
+ raise BackupPolicyError('Backup not found')
+ if not run.remote_key:
+ raise BackupPolicyError('This backup has no remote copy to verify')
+ from app.services.storage_provider_service import StorageProviderService
+ local = (run.get_metadata() or {}).get('remote_source') or run.storage_path
+ result = StorageProviderService.verify_file(run.remote_key, local)
+ run.verified = bool(result.get('verified'))
+ db.session.commit()
+ return {'success': True, 'verified': run.verified, 'detail': result}
+
+ @classmethod
+ def delete_run(cls, policy, run_id):
+ """Delete a backup run: local files, remote copy, and the row."""
+ run = cls.get_run(policy, run_id)
+ if not run:
+ raise BackupPolicyError('Backup not found')
+ # Local files
+ path = run.storage_path
+ try:
+ if path and os.path.exists(path):
+ if os.path.isdir(path):
+ shutil.rmtree(path, ignore_errors=True)
+ else:
+ os.remove(path)
+ except OSError as exc:
+ logger.warning('Failed to delete backup files at %s: %s', path, exc)
+ # Remote copy
+ if run.remote_key:
+ try:
+ from app.services.storage_provider_service import StorageProviderService
+ StorageProviderService.delete_file(run.remote_key)
+ except Exception as exc: # best-effort
+ logger.warning('Failed to delete remote backup %s: %s', run.remote_key, exc)
+ db.session.delete(run)
+ db.session.commit()
+ return True
+
+ @classmethod
+ def serialize_policy_view(cls, policy):
+ """Full payload for the protection panel: policy + status + projection."""
+ from sqlalchemy import func
+ from app.models.backup_run import BackupRun
+ from app.services.backup_cost_service import BackupCostService
+
+ last_run = (BackupRun.query.filter_by(policy_id=policy.id)
+ .order_by(BackupRun.started_at.desc()).first())
+
+ # Average size of recent successful runs → drives the projection.
+ recent_sizes = [r.size_local or 0 for r in (
+ BackupRun.query.filter_by(policy_id=policy.id, status='success')
+ .order_by(BackupRun.started_at.desc()).limit(10).all()
+ )]
+ avg_size = (sum(recent_sizes) / len(recent_sizes)) if recent_sizes else (policy.last_size or 0)
+
+ totals = db.session.query(
+ func.coalesce(func.sum(BackupRun.size_local), 0),
+ func.coalesce(func.sum(BackupRun.size_remote), 0),
+ ).filter(BackupRun.policy_id == policy.id).first()
+ storage_used = int((totals[0] or 0) + (totals[1] or 0))
+
+ scheduled = cls._scheduled_job(policy)
+ next_run = scheduled.next_run_at if (scheduled and scheduled.enabled and policy.enabled) else None
+
+ monthly = BackupCostService.project_monthly_cost(policy, avg_size)
+
+ return {
+ 'policy': policy.to_dict(),
+ 'last_run': last_run.to_dict() if last_run else None,
+ 'next_run_at': next_run.isoformat() if next_run else None,
+ 'monthly_cost': float(monthly),
+ 'monthly_cost_display': BackupCostService.format_cost(monthly),
+ 'storage_used': storage_used,
+ 'storage_used_human': format_bytes(storage_used),
+ 'remote_configured': BackupCostService.configured_remote_provider() is not None,
+ 'is_running': cls.is_running(policy),
+ }
+
+ # ------------------------------------------------------------------ #
+ # Notifications (best-effort)
+ # ------------------------------------------------------------------ #
+
+ @staticmethod
+ def _notify(event, name, data):
+ try:
+ from app.plugins_sdk import notify
+ notify.send(event, to='admins', data=data, category='backups')
+ except Exception as exc: # never let a notification failure break a backup
+ logger.debug('notify %s failed: %s', event, exc)
+
+ # ------------------------------------------------------------------ #
+ # Registration
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def register_jobs(cls):
+ """Register the policy backup + restore handlers with the job registry.
+ Called once at app startup (see app/__init__.py)."""
+ from app.jobs import registry
+ registry.register(BACKUP_POLICY_JOB_KIND, cls.run_backup_policy_job, replace=True)
+ registry.register(RESTORE_JOB_KIND, cls.run_restore_job, replace=True)
diff --git a/backend/app/services/backup_service.py b/backend/app/services/backup_service.py
index 2b7741c1..7092f962 100644
--- a/backend/app/services/backup_service.py
+++ b/backend/app/services/backup_service.py
@@ -804,6 +804,85 @@ class BackupService:
except Exception:
pass
+ # --- Smart backups (incremental + compression tiering) ---
+
+ @classmethod
+ def _compression_program(cls, compression):
+ """Return ``(tar --use-compress-program value, file extension)`` for a
+ compression tier. zstd is preferred for balanced/max; gzip is the
+ fallback when the zstd binary is missing."""
+ have_zstd = is_command_available('zstd')
+ if compression == 'fast':
+ return ('gzip', 'gz')
+ if compression == 'max':
+ return ('zstd -19 -T0', 'zst') if have_zstd else ('gzip -9', 'gz')
+ # balanced (default)
+ return ('zstd -3 -T0', 'zst') if have_zstd else ('gzip', 'gz')
+
+ @classmethod
+ def smart_backup_files(cls, source_path, dest_dir, kind, compression, snar_path):
+ """Create a (full|incremental) compressed tar of ``source_path`` into
+ ``dest_dir``.
+
+ Uses GNU ``tar --listed-incremental`` (level-0 for full, level-1+ for
+ incremental, sharing one ``.snar`` per policy). A full run resets the
+ ``.snar`` so the chain starts fresh. Falls back to a full Python
+ ``tarfile`` gzip archive when ``tar`` is unavailable (e.g. Windows dev),
+ which means incremental degrades gracefully to full.
+
+ Returns a dict: archive, size, compression, kind, incremental, ext.
+ """
+ os.makedirs(dest_dir, exist_ok=True)
+
+ if not (os.name == 'posix' and is_command_available('tar')):
+ archive = os.path.join(dest_dir, 'files.tar.gz')
+ with tarfile.open(archive, 'w:gz') as tar:
+ tar.add(source_path, arcname=os.path.basename(source_path))
+ return {'archive': archive, 'size': os.path.getsize(archive),
+ 'compression': 'gzip', 'kind': 'full', 'incremental': False, 'ext': 'gz'}
+
+ program, ext = cls._compression_program(compression)
+ archive = os.path.join(dest_dir, f'files.tar.{ext}')
+
+ # A full backup resets the incremental chain.
+ if kind == 'full' and os.path.exists(snar_path):
+ try:
+ os.remove(snar_path)
+ except OSError:
+ pass
+
+ os.makedirs(os.path.dirname(snar_path), exist_ok=True)
+ cmd = ['tar']
+ if program:
+ cmd.append(f'--use-compress-program={program}')
+ cmd.append(f'--listed-incremental={snar_path}')
+ cmd += ['-cf', archive, '-C', os.path.dirname(source_path) or '/', os.path.basename(source_path)]
+
+ result = subprocess.run(cmd, capture_output=True, text=True, timeout=1800)
+ if result.returncode != 0:
+ raise RuntimeError(f'tar failed: {(result.stderr or "").strip()[:300]}')
+ return {'archive': archive, 'size': os.path.getsize(archive),
+ 'compression': program, 'kind': kind, 'incremental': kind == 'incremental', 'ext': ext}
+
+ @classmethod
+ def restore_incremental_chain(cls, archives, restore_path):
+ """Restore an ordered list of incremental tar archives (full first) into
+ ``restore_path`` using ``tar --listed-incremental``. Each archive is
+ extracted in sequence, reconstructing the point-in-time state of the last
+ archive (including files deleted between increments)."""
+ if not archives:
+ raise RuntimeError('No archives to restore')
+ os.makedirs(restore_path, exist_ok=True)
+ parent = os.path.dirname(restore_path.rstrip('/')) or '/'
+ for archive in archives:
+ if not os.path.exists(archive):
+ raise RuntimeError(f'Backup archive missing: {archive}')
+ cmd = ['tar', '--listed-incremental=/dev/null', '-xf', archive, '-C', parent]
+ result = subprocess.run(cmd, capture_output=True, text=True, timeout=1800)
+ if result.returncode != 0:
+ raise RuntimeError(f'tar restore failed: {(result.stderr or "").strip()[:300]}')
+ return {'success': True, 'restore_path': restore_path}
+
# --- Scheduler (unified job system) ---
@classmethod
diff --git a/backend/migrations/versions/028_backup_policies.py b/backend/migrations/versions/028_backup_policies.py
new file mode 100644
index 00000000..554d7441
--- /dev/null
+++ b/backend/migrations/versions/028_backup_policies.py
@@ -0,0 +1,95 @@
+"""Backup protection policies + runs.
+
+Adds:
+- backup_policies
+- backup_runs
+
+Backs the WordPress/Services "Protection" panel: one policy per target, with the
+cron schedule mirrored into a ScheduledJob, and one backup_runs row per execution
+(the history view's source of truth).
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on boot
+before Alembic, so guard on the live schema.
+
+Revision ID: 028_backup_policies
+Revises: 027_dns_change_log
+Create Date: 2026-06-22
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '028_backup_policies'
+down_revision = '027_dns_change_log'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ existing = set(inspector.get_table_names())
+
+ if 'backup_policies' not in existing:
+ op.create_table(
+ 'backup_policies',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('target_type', sa.String(40), nullable=False),
+ sa.Column('target_id', sa.Integer, nullable=False),
+ sa.Column('enabled', sa.Boolean, nullable=False, server_default=sa.false()),
+ sa.Column('schedule_cron', sa.String(120), nullable=False, server_default='0 2 * * *'),
+ sa.Column('retention_count', sa.Integer, nullable=False, server_default='14'),
+ sa.Column('retention_days', sa.Integer, nullable=False, server_default='30'),
+ sa.Column('full_every_n_days', sa.Integer, nullable=False, server_default='7'),
+ sa.Column('compression', sa.String(20), nullable=False, server_default='balanced'),
+ sa.Column('remote_copy', sa.Boolean, nullable=False, server_default=sa.false()),
+ sa.Column('pre_backup_hook', sa.Text, nullable=True),
+ sa.Column('post_backup_hook', sa.Text, nullable=True),
+ sa.Column('last_run_at', sa.DateTime, nullable=True),
+ sa.Column('last_status', sa.String(20), nullable=True),
+ sa.Column('last_size', sa.BigInteger, nullable=True),
+ sa.Column('last_cost_local', sa.Numeric(10, 4), nullable=True),
+ sa.Column('last_cost_remote', sa.Numeric(10, 4), nullable=True),
+ sa.Column('last_job_id', sa.String(36), nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.Column('updated_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ sa.UniqueConstraint('target_type', 'target_id', name='uq_backup_policy_target'),
+ )
+ op.create_index('ix_backup_policies_target_type', 'backup_policies', ['target_type'])
+ op.create_index('ix_backup_policies_target_id', 'backup_policies', ['target_id'])
+
+ if 'backup_runs' not in existing:
+ op.create_table(
+ 'backup_runs',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('policy_id', sa.Integer, nullable=False),
+ sa.Column('job_id', sa.String(36), nullable=True),
+ sa.Column('kind', sa.String(20), nullable=False),
+ sa.Column('status', sa.String(20), nullable=False),
+ sa.Column('started_at', sa.DateTime, nullable=True),
+ sa.Column('finished_at', sa.DateTime, nullable=True),
+ sa.Column('duration_seconds', sa.Integer, nullable=True),
+ sa.Column('size_local', sa.BigInteger, nullable=True, server_default='0'),
+ sa.Column('size_remote', sa.BigInteger, nullable=True, server_default='0'),
+ sa.Column('cost_local', sa.Numeric(10, 4), nullable=True, server_default='0'),
+ sa.Column('cost_remote', sa.Numeric(10, 4), nullable=True, server_default='0'),
+ sa.Column('storage_path', sa.Text, nullable=True),
+ sa.Column('remote_key', sa.Text, nullable=True),
+ sa.Column('verified', sa.Boolean, nullable=True, server_default=sa.false()),
+ sa.Column('error_message', sa.Text, nullable=True),
+ sa.Column('metadata_json', sa.Text, nullable=True, server_default='{}'),
+ sa.PrimaryKeyConstraint('id'),
+ sa.ForeignKeyConstraint(['policy_id'], ['backup_policies.id']),
+ )
+ op.create_index('ix_backup_runs_policy_id', 'backup_runs', ['policy_id'])
+ op.create_index('ix_backup_runs_job_id', 'backup_runs', ['job_id'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ existing = set(inspector.get_table_names())
+ if 'backup_runs' in existing:
+ op.drop_table('backup_runs')
+ if 'backup_policies' in existing:
+ op.drop_table('backup_policies')
diff --git a/backend/tests/test_backup_protection.py b/backend/tests/test_backup_protection.py
new file mode 100644
index 00000000..91b6ae61
--- /dev/null
+++ b/backend/tests/test_backup_protection.py
@@ -0,0 +1,294 @@
+"""Tests for the backup "Protection" system: cost model, policy CRUD + schedule
+wiring, full/incremental decision, chain-aware retention, and a real incremental
+tar round-trip (skipped where GNU tar is unavailable, e.g. Windows dev)."""
+import os
+import shutil
+import subprocess
+from datetime import datetime, timedelta
+
+import pytest
+
+from app import db
+from app.services.backup_cost_service import BackupCostService, GB
+from app.services.backup_policy_service import BackupPolicyService, BackupPolicyError
+from app.services.backup_service import BackupService
+
+HAS_TAR = os.name == 'posix' and shutil.which('tar') is not None
+
+
+# --------------------------------------------------------------------------- #
+# Cost model
+# --------------------------------------------------------------------------- #
+
+def test_compute_cost_uses_per_gb_rate(app):
+ # 5 GB on S3 at the $0.023/GB default ≈ $0.115.
+ cost = BackupCostService.compute_cost(5 * GB, 's3')
+ assert abs(float(cost) - 0.115) < 0.0005
+ # Local is free by default — it's the operator's own server disk.
+ assert float(BackupCostService.compute_cost(5 * GB, 'local')) == 0.0
+
+
+def test_format_cost():
+ assert BackupCostService.format_cost(0) == '$0.00'
+ assert BackupCostService.format_cost(1.2) == '$1.20'
+ assert BackupCostService.format_cost(0.0006) == '$0.0006'
+
+
+def test_runs_per_month():
+ assert BackupCostService.runs_per_month('0 2 * * *') == 30 # daily
+ assert BackupCostService.runs_per_month('0 2 * * 0') in (4, 5) # weekly
+
+
+def test_expected_retained_count_and_projection(app, monkeypatch):
+ policy = BackupPolicyService.get_or_create_policy('application', 1001)
+ policy.schedule_cron = '0 2 * * *' # daily
+ policy.retention_count = 14
+ policy.retention_days = 30
+ # Daily for 30 days is capped by retention_count (14).
+ assert BackupCostService.expected_retained_count(policy) == 14
+
+ # With a non-zero local rate the projection is count * avg_size * rate.
+ monkeypatch.setattr(BackupCostService, 'get_rates',
+ classmethod(lambda cls: {'local': 0.01, 's3': 0.023, 'b2': 0.006}))
+ projected = BackupCostService.project_monthly_cost(policy, 1 * GB)
+ assert abs(float(projected) - 0.14) < 0.0005 # 14 * 1GB * $0.01
+
+
+# --------------------------------------------------------------------------- #
+# Policy CRUD + schedule wiring
+# --------------------------------------------------------------------------- #
+
+def test_policy_update_syncs_scheduled_job(app):
+ from app.jobs.models import ScheduledJob
+ policy = BackupPolicyService.get_or_create_policy('application', 2002)
+ BackupPolicyService.update_policy(policy, {
+ 'enabled': True, 'schedule_cron': '0 5 * * 0', 'retention_count': 7,
+ })
+ sched = ScheduledJob.query.filter_by(name='backup.application.2002').first()
+ assert sched is not None
+ assert sched.cron == '0 5 * * 0'
+ assert sched.kind == 'backup.policy.run'
+ assert sched.enabled is True
+ assert policy.retention_count == 7
+
+ # Toggling off propagates to the schedule (ensure() preserves enabled, so the
+ # service must push it explicitly).
+ BackupPolicyService.update_policy(policy, {'enabled': False})
+ sched = ScheduledJob.query.filter_by(name='backup.application.2002').first()
+ assert sched.enabled is False
+
+
+def test_policy_validation(app):
+ policy = BackupPolicyService.get_or_create_policy('application', 3003)
+ with pytest.raises(BackupPolicyError):
+ BackupPolicyService.update_policy(policy, {'retention_count': 0})
+ with pytest.raises(BackupPolicyError):
+ BackupPolicyService.update_policy(policy, {'schedule_cron': 'not a cron'})
+ with pytest.raises(BackupPolicyError):
+ BackupPolicyService.update_policy(policy, {'compression': 'turbo'})
+ # No remote storage configured -> enabling remote_copy is rejected.
+ with pytest.raises(BackupPolicyError):
+ BackupPolicyService.update_policy(policy, {'remote_copy': True})
+
+
+# --------------------------------------------------------------------------- #
+# Full vs incremental decision
+# --------------------------------------------------------------------------- #
+
+def test_decide_kind(app, tmp_path, monkeypatch):
+ from app.models.backup_run import BackupRun
+ monkeypatch.setattr(BackupService, 'BACKUP_BASE_DIR', str(tmp_path))
+ policy = BackupPolicyService.get_or_create_policy('application', 4004)
+
+ # No snar yet -> full.
+ assert BackupPolicyService._decide_kind(policy) == 'full'
+
+ # Snar exists but no prior full run -> still full.
+ snar = BackupPolicyService._snar_path(policy)
+ os.makedirs(os.path.dirname(snar), exist_ok=True)
+ open(snar, 'w').close()
+ assert BackupPolicyService._decide_kind(policy) == 'full'
+
+ # A recent full run -> next is incremental.
+ full = BackupRun(policy_id=policy.id, kind='full', status='success',
+ started_at=datetime.utcnow())
+ db.session.add(full)
+ db.session.commit()
+ assert BackupPolicyService._decide_kind(policy) == 'incremental'
+
+ # Full is older than full_every_n_days -> full again.
+ full.started_at = datetime.utcnow() - timedelta(days=policy.full_every_n_days + 1)
+ db.session.commit()
+ assert BackupPolicyService._decide_kind(policy) == 'full'
+
+ # WordPress targets are always full.
+ wp = BackupPolicyService.get_or_create_policy('wordpress_site', 4040)
+ assert BackupPolicyService._decide_kind(wp) == 'full'
+
+
+# --------------------------------------------------------------------------- #
+# Retention
+# --------------------------------------------------------------------------- #
+
+def _mk_run(policy_id, kind, age_days, status='success', meta=None):
+ from app.models.backup_run import BackupRun
+ run = BackupRun(policy_id=policy_id, kind=kind, status=status,
+ started_at=datetime.utcnow() - timedelta(days=age_days))
+ if meta:
+ run.set_metadata(meta)
+ db.session.add(run)
+ db.session.commit()
+ return run
+
+
+def test_retention_keeps_recent_and_deletes_old(app):
+ from app.models.backup_run import BackupRun
+ policy = BackupPolicyService.get_or_create_policy('application', 5005)
+ policy.retention_count = 3
+ policy.retention_days = 30
+ db.session.commit()
+
+ # 5 daily fulls; the oldest two are out of count, all within days.
+ runs = [_mk_run(policy.id, 'full', age) for age in (0, 1, 2, 3, 4)]
+ BackupPolicyService.apply_retention(policy)
+ remaining = {r.id for r in BackupRun.query.filter_by(policy_id=policy.id).all()}
+ # Keep the newest 3 (ages 0,1,2); drop ages 3,4.
+ assert runs[0].id in remaining and runs[1].id in remaining and runs[2].id in remaining
+ assert runs[3].id not in remaining and runs[4].id not in remaining
+
+
+def test_retention_always_keeps_last_even_if_too_old(app):
+ from app.models.backup_run import BackupRun
+ policy = BackupPolicyService.get_or_create_policy('application', 5006)
+ policy.retention_count = 5
+ policy.retention_days = 7
+ db.session.commit()
+ # One ancient backup, well past retention_days, is still the only/most recent.
+ old = _mk_run(policy.id, 'full', 99)
+ BackupPolicyService.apply_retention(policy)
+ assert BackupRun.query.get(old.id) is not None
+
+
+def test_retention_protects_incremental_chain(app):
+ from app.models.backup_run import BackupRun
+ policy = BackupPolicyService.get_or_create_policy('application', 5007)
+ policy.retention_count = 2 # only the 2 newest would normally survive
+ policy.retention_days = 30
+ db.session.commit()
+
+ full = _mk_run(policy.id, 'full', 5)
+ incr1 = _mk_run(policy.id, 'incremental', 3, meta={'incremental': True, 'full_run_id': full.id})
+ incr2 = _mk_run(policy.id, 'incremental', 1, meta={'incremental': True, 'full_run_id': full.id})
+
+ BackupPolicyService.apply_retention(policy)
+ remaining = {r.id for r in BackupRun.query.filter_by(policy_id=policy.id).all()}
+ # incr2 + incr1 are the 2 newest; the full is older than retention_count but
+ # MUST be protected because the kept incrementals depend on it.
+ assert full.id in remaining
+ assert incr1.id in remaining
+ assert incr2.id in remaining
+
+
+# --------------------------------------------------------------------------- #
+# Real incremental tar round-trip (Linux/macOS only)
+# --------------------------------------------------------------------------- #
+
[email protected](not HAS_TAR, reason='GNU tar not available (e.g. Windows dev)')
+def test_smart_backup_files_incremental_roundtrip(tmp_path):
+ source = tmp_path / 'site'
+ source.mkdir()
+ (source / 'a.txt').write_text('first')
+ dest_full = tmp_path / 'full'
+ snar = str(tmp_path / 'incremental.snar')
+
+ full = BackupService.smart_backup_files(str(source), str(dest_full), 'full', 'balanced', snar)
+ assert full['kind'] == 'full' and os.path.exists(full['archive'])
+
+ # Change the tree, then take an incremental.
+ (source / 'b.txt').write_text('second')
+ dest_incr = tmp_path / 'incr'
+ incr = BackupService.smart_backup_files(str(source), str(dest_incr), 'incremental', 'fast', snar)
+ assert incr['incremental'] is True
+ # Real proof of incrementality: the incremental archive holds ONLY the
+ # changed file (b.txt), not the unchanged a.txt. (Raw byte size isn't a
+ # reliable signal for tiny trees — tar/gzip fixed overhead dominates.)
+ listing = subprocess.run(['tar', '-tf', incr['archive']], capture_output=True, text=True).stdout
+ names = [ln.rstrip('/') for ln in listing.splitlines()]
+ assert any(n.endswith('b.txt') for n in names), listing
+ assert not any(n.endswith('a.txt') for n in names), listing
+
+ # Restore the chain (full -> incr) and confirm both files reappear.
+ restore_to = tmp_path / 'restored' / 'site'
+ BackupService.restore_incremental_chain([full['archive'], incr['archive']], str(restore_to))
+ assert (restore_to / 'a.txt').read_text() == 'first'
+ assert (restore_to / 'b.txt').read_text() == 'second'
+
+
+# --------------------------------------------------------------------------- #
+# Restore wiring
+# --------------------------------------------------------------------------- #
+
+def test_chain_archives_orders_full_then_incrementals(app, tmp_path, monkeypatch):
+ from app.models.backup_run import BackupRun
+ monkeypatch.setattr(BackupService, 'BACKUP_BASE_DIR', str(tmp_path))
+ policy = BackupPolicyService.get_or_create_policy('application', 6006)
+
+ def _run(kind, age, full_id=None):
+ archive = tmp_path / f'{kind}_{age}.tar.gz'
+ archive.write_text('x')
+ meta = {'primary_archive': str(archive), 'incremental': kind == 'incremental'}
+ if full_id:
+ meta['full_run_id'] = full_id
+ run = BackupRun(policy_id=policy.id, kind=kind, status='success',
+ started_at=datetime.utcnow() - timedelta(days=age))
+ run.set_metadata(meta)
+ db.session.add(run)
+ db.session.commit()
+ return run
+
+ full = _run('full', 5)
+ incr1 = _run('incremental', 3, full_id=full.id)
+ incr2 = _run('incremental', 1, full_id=full.id)
+
+ # Restoring incr2 needs full -> incr1 -> incr2 in order.
+ chain = BackupPolicyService._chain_archives(policy, incr2)
+ assert chain == [
+ full.get_metadata()['primary_archive'],
+ incr1.get_metadata()['primary_archive'],
+ incr2.get_metadata()['primary_archive'],
+ ]
+ # Restoring the full alone needs only the full.
+ assert BackupPolicyService._chain_archives(policy, full) == [full.get_metadata()['primary_archive']]
+
+
+def test_request_restore_enqueues_job(app):
+ from app.models.backup_run import BackupRun
+ policy = BackupPolicyService.get_or_create_policy('application', 7007)
+ run = BackupRun(policy_id=policy.id, kind='full', status='success',
+ started_at=datetime.utcnow())
+ db.session.add(run)
+ db.session.commit()
+
+ job = BackupPolicyService.request_restore(policy, run.id, {'scope': 'full', 'safety_backup': True})
+ assert job.kind == 'restore.run'
+ payload = job.get_payload()
+ assert payload['run_id'] == run.id
+ assert payload['policy_id'] == policy.id
+ assert payload['scope'] == 'full'
+
+ # A non-existent run is rejected.
+ with pytest.raises(BackupPolicyError):
+ BackupPolicyService.request_restore(policy, 999999, {})
+
+
[email protected](not HAS_TAR, reason='GNU tar not available')
+def test_full_backup_resets_snar(tmp_path):
+ source = tmp_path / 'app'
+ source.mkdir()
+ (source / 'x').write_text('x')
+ snar = str(tmp_path / 'snar.snar')
+ BackupService.smart_backup_files(str(source), str(tmp_path / 'f1'), 'full', 'fast', snar)
+ assert os.path.exists(snar)
+ # A second full deletes + recreates the snar (fresh level-0 chain).
+ res = BackupService.smart_backup_files(str(source), str(tmp_path / 'f2'), 'full', 'fast', snar)
+ assert res['kind'] == 'full' and os.path.exists(snar)