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(dns): change log + admin notice on failure (Phase 2 backend)

Juan Denis38a258ee2d11
diff --git a/backend/app/api/dns_zones.py b/backend/app/api/dns_zones.py
index b0380867..305d7146 100644
--- a/backend/app/api/dns_zones.py
+++ b/backend/app/api/dns_zones.py
@@ -141,6 +141,22 @@ def zone_mirror(zone_id):
return jsonify(DNSZoneService.list_provider_records(zone))
+@dns_zones_bp.route('/changes', methods=['GET'])
+@jwt_required()
+def list_dns_changes():
+ """The 'Changes to your Cloudflare' activity feed — every record write ServerKit
+ sent to a connected provider. Filter by ?config_id=, ?zone= (provider zone id),
+ ?result= (ok|error|conflict|skipped)."""
+ from app.services.dns_change_service import DnsChangeService
+ config_id = request.args.get('config_id', type=int)
+ zone = request.args.get('zone')
+ result = request.args.get('result')
+ limit = request.args.get('limit', default=100, type=int)
+ changes = DnsChangeService.list(config_id=config_id, provider_zone_id=zone,
+ result=result, limit=min(max(limit, 1), 500))
+ return jsonify({'changes': [c.to_dict() for c in changes]})
+
+
@dns_zones_bp.route('/<int:zone_id>/export', methods=['GET'])
@jwt_required()
def export_zone(zone_id):
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 62fb85aa..1dcf364d 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -30,6 +30,7 @@ from app.models.server_template import ServerTemplate, ServerTemplateAssignment
from app.models.workspace import Workspace, WorkspaceMember, WorkspaceApiKey, ResourceGrant
from app.models.dns_zone import DNSZone, DNSRecord
from app.models.managed_dns_record import ManagedDnsRecord
+from app.models.dns_change import DnsChange
from app.models.tunnel import Tunnel
from app.models.exposed_service import ExposedService
from app.models.status_page import StatusPage, StatusComponent, HealthCheck, StatusIncident, StatusIncidentUpdate
@@ -62,7 +63,7 @@ __all__ = [
'AgentPlugin', 'AgentPluginInstall',
'ServerTemplate', 'ServerTemplateAssignment',
'Workspace', 'WorkspaceMember', 'WorkspaceApiKey', 'ResourceGrant',
- 'DNSZone', 'DNSRecord', 'ManagedDnsRecord',
+ 'DNSZone', 'DNSRecord', 'ManagedDnsRecord', 'DnsChange',
'Tunnel', 'ExposedService',
'StatusPage', 'StatusComponent', 'HealthCheck', 'StatusIncident', 'StatusIncidentUpdate',
'CloudProvider', 'CloudServer', 'CloudSnapshot',
diff --git a/backend/app/models/dns_change.py b/backend/app/models/dns_change.py
new file mode 100644
index 00000000..75e0a5de
--- /dev/null
+++ b/backend/app/models/dns_change.py
@@ -0,0 +1,46 @@
+from datetime import datetime
+from app import db
+
+
+class DnsChange(db.Model):
+ """Audit trail of every DNS record write ServerKit sends to a connected provider.
+
+ Powers the "Changes to your Cloudflare" activity feed on the connection — so the
+ user can always see exactly what the panel created, updated, or deleted in their
+ zone (and what failed). Written at the single write choke point
+ (DnsOwnershipService.guarded_upsert / guarded_delete), so coverage is complete.
+ """
+ __tablename__ = 'dns_changes'
+
+ id = db.Column(db.Integer, primary_key=True)
+ dns_provider_config_id = db.Column(
+ db.Integer, db.ForeignKey('dns_provider_configs.id'), nullable=True, index=True)
+ provider = db.Column(db.String(64), nullable=False)
+ provider_zone_id = db.Column(db.String(128), index=True)
+ action = db.Column(db.String(16), nullable=False) # create | update | delete
+ record_type = db.Column(db.String(10))
+ name = db.Column(db.String(256))
+ content = db.Column(db.Text) # value we set (after)
+ provider_record_id = db.Column(db.String(128))
+ source = db.Column(db.String(40)) # zone|ddns|wordpress|email|auto-dns|caa|...
+ result = db.Column(db.String(16), nullable=False) # ok | error | conflict | skipped
+ error = db.Column(db.Text)
+
+ created_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'dns_provider_config_id': self.dns_provider_config_id,
+ 'provider': self.provider,
+ 'provider_zone_id': self.provider_zone_id,
+ 'action': self.action,
+ 'record_type': self.record_type,
+ 'name': self.name,
+ 'content': self.content,
+ 'provider_record_id': self.provider_record_id,
+ 'source': self.source,
+ 'result': self.result,
+ 'error': self.error,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
diff --git a/backend/app/notifications/catalog.py b/backend/app/notifications/catalog.py
index e0464526..73ee2909 100644
--- a/backend/app/notifications/catalog.py
+++ b/backend/app/notifications/catalog.py
@@ -49,6 +49,12 @@ _CATALOG = {
'severity': 'warning',
'category': 'system',
},
+ 'dns.sync_failed': {
+ 'title': 'DNS sync failed: {record}',
+ 'template': 'generic',
+ 'severity': 'warning',
+ 'category': 'system',
+ },
# Multi-alert monitoring digest (used by the legacy send_all path).
'monitoring.alert': {
'title': 'ServerKit alert',
diff --git a/backend/app/services/dns_change_service.py b/backend/app/services/dns_change_service.py
new file mode 100644
index 00000000..964cfb81
--- /dev/null
+++ b/backend/app/services/dns_change_service.py
@@ -0,0 +1,67 @@
+"""The DNS change activity log — every record write ServerKit sends to a connected
+provider is recorded here, and failures are surfaced to admins.
+
+Recording happens at the single write choke point
+(:meth:`DnsOwnershipService.guarded_upsert` / ``guarded_delete``), so the feed on a
+connection is a complete, honest account of what the panel changed in the user's
+zone — successes, foreign-record refusals, and failures alike.
+"""
+import logging
+
+from app import db
+from app.models.dns_change import DnsChange
+
+logger = logging.getLogger(__name__)
+
+
+class DnsChangeService:
+
+ @staticmethod
+ def record(*, provider, provider_zone_id, action, record_type=None, name=None,
+ content=None, provider_record_id=None, source=None, result='ok',
+ error=None, config_id=None):
+ """Append a change to the log. On a real failure (``result == 'error'``) also
+ surface an admin-facing notice. Never raises — logging a change must not break
+ the write it describes."""
+ try:
+ row = DnsChange(
+ provider=provider, provider_zone_id=provider_zone_id, action=action,
+ record_type=record_type, name=name, content=content,
+ provider_record_id=provider_record_id, source=source,
+ result=result, error=error, dns_provider_config_id=config_id)
+ db.session.add(row)
+ db.session.commit()
+ except Exception as e:
+ db.session.rollback()
+ logger.warning('Failed to record DNS change: %s', e)
+ return None
+
+ if result == 'error':
+ DnsChangeService._notify_failure(row)
+ return row
+
+ @staticmethod
+ def _notify_failure(row):
+ """Surface a failed provider write to admins (best-effort)."""
+ try:
+ from app.plugins_sdk import notify
+ notify.send('dns.sync_failed', to='admins', data={
+ 'record': f'{row.record_type or ""} {row.name or ""}'.strip(),
+ 'zone': row.provider_zone_id,
+ 'provider': row.provider,
+ 'action': row.action,
+ 'error': row.error or 'unknown error',
+ }, severity='warning', category='system')
+ except Exception as e:
+ logger.warning('DNS failure notification skipped: %s', e)
+
+ @staticmethod
+ def list(config_id=None, provider_zone_id=None, result=None, limit=100):
+ q = DnsChange.query
+ if config_id:
+ q = q.filter_by(dns_provider_config_id=config_id)
+ if provider_zone_id:
+ q = q.filter_by(provider_zone_id=provider_zone_id)
+ if result:
+ q = q.filter_by(result=result)
+ return q.order_by(DnsChange.created_at.desc(), DnsChange.id.desc()).limit(limit).all()
diff --git a/backend/app/services/dns_ownership_service.py b/backend/app/services/dns_ownership_service.py
index dbbb2ff6..9833755f 100644
--- a/backend/app/services/dns_ownership_service.py
+++ b/backend/app/services/dns_ownership_service.py
@@ -106,6 +106,7 @@ class DnsOwnershipService:
``conflict=True`` when a foreign record blocked an automatic write.
"""
from app.services.dns.cloudflare import parse_caa_value
+ from app.services.dns_change_service import DnsChangeService
record_id = known_record_id
if record_id is None:
@@ -119,22 +120,35 @@ class DnsOwnershipService:
else:
logger.warning('Refusing to overwrite foreign DNS record %s %s in zone %s',
spec.record_type, spec.name, provider_zone_id)
- return {'success': False, 'conflict': True,
- 'error': (f'{spec.record_type} record {spec.name} already exists in '
- f'this zone and was not created by ServerKit — left untouched.')}
-
+ msg = (f'{spec.record_type} record {spec.name} already exists in this zone '
+ f'and was not created by ServerKit — left untouched.')
+ DnsChangeService.record(
+ provider=provider, provider_zone_id=provider_zone_id, action='create',
+ record_type=spec.record_type, name=spec.name, content=spec.content,
+ source=source, result='conflict', error=msg, config_id=config_id)
+ return {'success': False, 'conflict': True, 'error': msg}
+
+ action = 'update' if record_id else 'create'
res = client.upsert(provider_zone_id, spec, record_id=record_id)
if res.get('success'):
DnsOwnershipService.record_write(
provider, provider_zone_id, spec.record_type, spec.name,
provider_record_id=res.get('record_id'), content=spec.content,
source=source, app_id=app_id, config_id=config_id)
+ DnsChangeService.record(
+ provider=provider, provider_zone_id=provider_zone_id, action=action,
+ record_type=spec.record_type, name=spec.name, content=spec.content,
+ provider_record_id=res.get('record_id'), source=source,
+ result='ok' if res.get('success') else 'error',
+ error=None if res.get('success') else res.get('error'), config_id=config_id)
return res
@staticmethod
- def guarded_delete(client, *, provider_zone_id, record_type, name, provider_record_id=None):
+ def guarded_delete(client, *, provider_zone_id, record_type, name, provider_record_id=None,
+ provider='cloudflare', source=None, config_id=None):
"""Delete only a record ServerKit owns; never a foreign one. Clears our
- ledger entry on success."""
+ ledger entry and logs the change on success."""
+ from app.services.dns_change_service import DnsChangeService
if provider_record_id:
owned = DnsOwnershipService.owns(provider_zone_id, provider_record_id=provider_record_id)
else:
@@ -146,4 +160,9 @@ class DnsOwnershipService:
record_type=record_type, name=name)
DnsOwnershipService.record_delete(provider_zone_id, record_type=record_type,
name=name, provider_record_id=provider_record_id)
+ DnsChangeService.record(
+ provider=provider, provider_zone_id=provider_zone_id, action='delete',
+ record_type=record_type, name=name, provider_record_id=provider_record_id,
+ source=source, result='ok' if res.get('success') else 'error',
+ error=None if res.get('success') else res.get('error'), config_id=config_id)
return res
diff --git a/backend/app/services/dns_provider_service.py b/backend/app/services/dns_provider_service.py
index e2a253fd..38c74ff1 100644
--- a/backend/app/services/dns_provider_service.py
+++ b/backend/app/services/dns_provider_service.py
@@ -359,7 +359,7 @@ class DNSProviderService:
from app.services.dns_ownership_service import DnsOwnershipService
return DnsOwnershipService.guarded_delete(
cls._cloudflare_client(config), provider_zone_id=zone_id,
- record_type=record_type, name=name)
+ record_type=record_type, name=name, config_id=config.id)
@staticmethod
def _host_relative_to_zone(name: str, zone: str) -> str:
diff --git a/backend/app/services/dns_zone_service.py b/backend/app/services/dns_zone_service.py
index 32fc163f..fbf2d8f4 100644
--- a/backend/app/services/dns_zone_service.py
+++ b/backend/app/services/dns_zone_service.py
@@ -442,4 +442,5 @@ class DNSZoneService:
elif action == 'delete' and record.provider_record_id:
DnsOwnershipService.guarded_delete(
client, provider_zone_id=zone_id, record_type=record.record_type,
- name=record.name, provider_record_id=record.provider_record_id)
+ name=record.name, provider_record_id=record.provider_record_id,
+ source='zone', config_id=zone.dns_provider_config_id)
diff --git a/backend/migrations/versions/027_dns_change_log.py b/backend/migrations/versions/027_dns_change_log.py
new file mode 100644
index 00000000..8439a080
--- /dev/null
+++ b/backend/migrations/versions/027_dns_change_log.py
@@ -0,0 +1,57 @@
+"""DNS change activity log.
+
+Adds:
+- dns_changes
+
+Audit trail of every record write ServerKit sends to a connected provider, powering
+the "Changes to your Cloudflare" activity feed on the connection.
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on boot
+before Alembic, so guard on the live schema.
+
+Revision ID: 027_dns_change_log
+Revises: 026_managed_dns_records
+Create Date: 2026-06-22
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '027_dns_change_log'
+down_revision = '026_managed_dns_records'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if 'dns_changes' in set(inspector.get_table_names()):
+ return
+ op.create_table(
+ 'dns_changes',
+ sa.Column('id', sa.Integer, nullable=False),
+ sa.Column('dns_provider_config_id', sa.Integer, nullable=True),
+ sa.Column('provider', sa.String(64), nullable=False),
+ sa.Column('provider_zone_id', sa.String(128), nullable=True),
+ sa.Column('action', sa.String(16), nullable=False),
+ sa.Column('record_type', sa.String(10), nullable=True),
+ sa.Column('name', sa.String(256), nullable=True),
+ sa.Column('content', sa.Text, nullable=True),
+ sa.Column('provider_record_id', sa.String(128), nullable=True),
+ sa.Column('source', sa.String(40), nullable=True),
+ sa.Column('result', sa.String(16), nullable=False),
+ sa.Column('error', sa.Text, nullable=True),
+ sa.Column('created_at', sa.DateTime, nullable=True),
+ sa.PrimaryKeyConstraint('id'),
+ )
+ op.create_index('ix_dns_changes_dns_provider_config_id', 'dns_changes', ['dns_provider_config_id'])
+ op.create_index('ix_dns_changes_provider_zone_id', 'dns_changes', ['provider_zone_id'])
+ op.create_index('ix_dns_changes_created_at', 'dns_changes', ['created_at'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if 'dns_changes' not in set(inspector.get_table_names()):
+ return
+ op.drop_table('dns_changes')
diff --git a/backend/tests/test_dns_change_log.py b/backend/tests/test_dns_change_log.py
new file mode 100644
index 00000000..9330e5b3
--- /dev/null
+++ b/backend/tests/test_dns_change_log.py
@@ -0,0 +1,117 @@
+"""Proving tests for the DNS change log + failure notification (Phase 2).
+
+Every record write ServerKit sends to a connected provider is recorded at the write
+choke point (guarded_upsert / guarded_delete) — successes, foreign-record refusals,
+and failures — and a real failure surfaces an admin notice.
+"""
+
+
+class FakeClient:
+ def __init__(self, existing_id=None, upsert_result=None):
+ self.existing_id = existing_id
+ self.upsert_result = upsert_result or {'success': True, 'record_id': 'NEW'}
+
+ def find_record_id(self, zone_id, record_type, name, caa=None):
+ return self.existing_id
+
+ def upsert(self, zone_id, spec, record_id=None):
+ return self.upsert_result
+
+ def delete(self, zone_id, record_id=None, record_type=None, name=None):
+ return {'success': True}
+
+
+def _spec(rtype='A', name='www.example.com', content='1.2.3.4'):
+ from app.services.dns.base import DnsRecordSpec
+ return DnsRecordSpec(rtype, name, content)
+
+
+# ── recording ────────────────────────────────────────────────────────────────
+
+def test_successful_write_logs_ok(app):
+ from app.services.dns_ownership_service import DnsOwnershipService as O
+ from app.models.dns_change import DnsChange
+ O.guarded_upsert(FakeClient(upsert_result={'success': True, 'record_id': 'R1'}),
+ provider='cloudflare', provider_zone_id='z1', spec=_spec(),
+ source='zone', config_id=7)
+ row = DnsChange.query.filter_by(provider_zone_id='z1', name='www.example.com').first()
+ assert row.result == 'ok' and row.action == 'create'
+ assert row.provider_record_id == 'R1' and row.source == 'zone'
+ assert row.dns_provider_config_id == 7
+
+
+def test_foreign_conflict_is_logged(app):
+ from app.services.dns_ownership_service import DnsOwnershipService as O
+ from app.models.dns_change import DnsChange
+ O.guarded_upsert(FakeClient(existing_id='FOREIGN'), provider='cloudflare',
+ provider_zone_id='z1', spec=_spec(name='maria.example.com'),
+ source='auto-dns', allow_foreign=False)
+ row = DnsChange.query.filter_by(provider_zone_id='z1', name='maria.example.com').first()
+ assert row.result == 'conflict' and row.action == 'create'
+
+
+def test_failed_write_logs_error_and_notifies(app, monkeypatch):
+ from app.services.dns_ownership_service import DnsOwnershipService as O
+ from app.services.dns_change_service import DnsChangeService
+ from app.models.dns_change import DnsChange
+
+ notified = {'n': 0}
+ monkeypatch.setattr(DnsChangeService, '_notify_failure',
+ staticmethod(lambda row: notified.update(n=notified['n'] + 1)))
+
+ O.guarded_upsert(FakeClient(upsert_result={'success': False, 'error': 'boom'}),
+ provider='cloudflare', provider_zone_id='z1', spec=_spec(), source='zone')
+ row = DnsChange.query.filter_by(provider_zone_id='z1', name='www.example.com').first()
+ assert row.result == 'error' and row.error == 'boom'
+ assert notified['n'] == 1
+
+
+def test_delete_is_logged(app):
+ from app.services.dns_ownership_service import DnsOwnershipService as O
+ from app.models.dns_change import DnsChange
+ O.record_write('cloudflare', 'z1', 'A', 'www.example.com', provider_record_id='R1', source='zone')
+ O.guarded_delete(FakeClient(), provider_zone_id='z1', record_type='A',
+ name='www.example.com', provider_record_id='R1', source='zone', config_id=3)
+ row = DnsChange.query.filter_by(provider_zone_id='z1', action='delete').first()
+ assert row is not None and row.result == 'ok' and row.dns_provider_config_id == 3
+
+
+# ── listing + filtering ──────────────────────────────────────────────────────
+
+def test_list_filters_by_config_and_result(app):
+ from app.services.dns_change_service import DnsChangeService as C
+ C.record(provider='cloudflare', provider_zone_id='ZA', action='create',
+ record_type='A', name='a.example.com', result='ok', config_id=1)
+ C.record(provider='cloudflare', provider_zone_id='ZB', action='create',
+ record_type='A', name='b.example.com', result='error', error='x', config_id=2)
+
+ assert {c.name for c in C.list(config_id=1)} == {'a.example.com'}
+ assert {c.name for c in C.list(result='error')} == {'b.example.com'}
+ assert {c.name for c in C.list(provider_zone_id='ZB')} == {'b.example.com'}
+
+
+# ── notify failure path is best-effort ───────────────────────────────────────
+
+def test_notify_failure_never_raises(app, monkeypatch):
+ from app.services.dns_change_service import DnsChangeService
+
+ def boom(*a, **k):
+ raise RuntimeError('notify down')
+ # Even if the notifier blows up, recording the change must not raise.
+ monkeypatch.setattr('app.plugins_sdk.notify.send', boom, raising=False)
+ row = DnsChangeService.record(provider='cloudflare', provider_zone_id='z1',
+ action='create', record_type='A', name='x.example.com',
+ result='error', error='whatever')
+ assert row is not None and row.result == 'error'
+
+
+# ── API ──────────────────────────────────────────────────────────────────────
+
+def test_changes_endpoint_returns_feed(app, client, auth_headers):
+ from app.services.dns_change_service import DnsChangeService
+ DnsChangeService.record(provider='cloudflare', provider_zone_id='Z', action='create',
+ record_type='A', name='www.example.com', result='ok', config_id=5)
+ resp = client.get('/api/v1/dns/changes?config_id=5', headers=auth_headers)
+ assert resp.status_code == 200
+ names = [c['name'] for c in resp.get_json()['changes']]
+ assert 'www.example.com' in names