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.

refactor(models): one JsonColumnMixin instead of 24 hand-rolled copies

Juan Denis2365a324086c
diff --git a/backend/app/models/api_key.py b/backend/app/models/api_key.py
index 4ece9594..f412e02f 100644
--- a/backend/app/models/api_key.py
+++ b/backend/app/models/api_key.py
@@ -1,12 +1,12 @@
"""API Key model for programmatic API access."""
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
import hashlib
-import json
import secrets
-class ApiKey(db.Model):
+class ApiKey(JsonColumnMixin, db.Model):
"""API key for programmatic access to the ServerKit API."""
__tablename__ = 'api_keys'
@@ -47,19 +47,11 @@ class ApiKey(db.Model):
def get_scopes(self):
"""Return parsed scopes list."""
- if self.scopes:
- try:
- return json.loads(self.scopes)
- except (json.JSONDecodeError, TypeError):
- return []
- return []
+ return self._json_read('scopes', [])
def set_scopes(self, scopes_list):
"""Set scopes from a list."""
- if scopes_list:
- self.scopes = json.dumps(scopes_list)
- else:
- self.scopes = None
+ self._json_write('scopes', scopes_list)
def is_expired(self):
"""Check if the key has expired."""
diff --git a/backend/app/models/application_manifest.py b/backend/app/models/application_manifest.py
index 2953428b..4aff954c 100644
--- a/backend/app/models/application_manifest.py
+++ b/backend/app/models/application_manifest.py
@@ -10,6 +10,7 @@ import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
# status values
@@ -19,7 +20,7 @@ STATUS_DRIFTED = 'drifted' # live state diverged from the manifest
STATUS_ERROR = 'error' # last apply / parse failed
-class ApplicationManifest(db.Model):
+class ApplicationManifest(JsonColumnMixin, db.Model):
__tablename__ = 'application_manifests'
id = db.Column(db.Integer, primary_key=True)
@@ -46,12 +47,7 @@ class ApplicationManifest(db.Model):
)
def get_normalized(self):
- if not self.normalized_json:
- return None
- try:
- return json.loads(self.normalized_json)
- except Exception:
- return None
+ return self._json_read('normalized_json', None)
def set_normalized(self, value):
self.normalized_json = json.dumps(value) if value is not None else None
diff --git a/backend/app/models/application_preview.py b/backend/app/models/application_preview.py
index 5b5a3d4c..f56754d1 100644
--- a/backend/app/models/application_preview.py
+++ b/backend/app/models/application_preview.py
@@ -9,13 +9,13 @@ Two tables:
* ``application_previews`` — one row per live PR preview.
* ``application_preview_settings`` — per-application opt-in + domain template.
"""
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class ApplicationPreview(db.Model):
+class ApplicationPreview(JsonColumnMixin, db.Model):
"""A single PR preview environment for an application."""
__tablename__ = 'application_previews'
@@ -52,16 +52,10 @@ class ApplicationPreview(db.Model):
def get_container_ids(self):
"""The provisioned container ids as a list (empty when unset/invalid)."""
- if not self.container_ids:
- return []
- try:
- val = json.loads(self.container_ids)
- return val if isinstance(val, list) else []
- except (ValueError, TypeError):
- return []
+ return self._json_read('container_ids', [], expect=list)
def set_container_ids(self, ids):
- self.container_ids = json.dumps(list(ids or []))
+ self._json_write('container_ids', list(ids or []), falsy='[]')
def to_dict(self):
return {
diff --git a/backend/app/models/audit_log.py b/backend/app/models/audit_log.py
index bd256585..b945637a 100644
--- a/backend/app/models/audit_log.py
+++ b/backend/app/models/audit_log.py
@@ -1,9 +1,9 @@
from datetime import datetime
from app import db
-import json
+from app.models.json_column_mixin import JsonColumnMixin
-class AuditLog(db.Model):
+class AuditLog(JsonColumnMixin, db.Model):
"""Audit log for tracking user actions."""
__tablename__ = 'audit_logs'
@@ -65,19 +65,11 @@ class AuditLog(db.Model):
def get_details(self):
"""Return parsed details JSON."""
- if self.details:
- try:
- return json.loads(self.details)
- except (json.JSONDecodeError, TypeError):
- return {}
- return {}
+ return self._json_read('details')
def set_details(self, details_dict):
"""Set details from a dictionary."""
- if details_dict:
- self.details = json.dumps(details_dict)
- else:
- self.details = None
+ self._json_write('details', details_dict)
def to_dict(self):
return {
diff --git a/backend/app/models/backup_policy.py b/backend/app/models/backup_policy.py
index 33e8422c..dddbbca7 100644
--- a/backend/app/models/backup_policy.py
+++ b/backend/app/models/backup_policy.py
@@ -1,8 +1,8 @@
-import json
from datetime import datetime
from decimal import Decimal
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
# Every CORE data-protection target the unified policy system can back up (§8).
# 'application' is the original target; 'database', 'files', and 'server' were
@@ -27,7 +27,7 @@ def _num(value):
return value
-class BackupPolicy(db.Model):
+class BackupPolicy(JsonColumnMixin, db.Model):
"""Automated backup ("protection") policy for a single target.
A target is a generic application (``target_type='application'``), a
@@ -103,16 +103,10 @@ class BackupPolicy(db.Model):
def get_target_meta(self):
"""Parsed target_meta_json (always a dict)."""
- if not self.target_meta_json:
- return {}
- try:
- data = json.loads(self.target_meta_json)
- return data if isinstance(data, dict) else {}
- except (ValueError, TypeError):
- return {}
+ return self._json_read('target_meta_json', expect=dict)
def set_target_meta(self, value):
- self.target_meta_json = json.dumps(value or {})
+ self._json_write('target_meta_json', value, falsy='{}')
def to_dict(self):
return {
diff --git a/backend/app/models/backup_run.py b/backend/app/models/backup_run.py
index a39012d8..6f065589 100644
--- a/backend/app/models/backup_run.py
+++ b/backend/app/models/backup_run.py
@@ -1,8 +1,8 @@
-import json
from datetime import datetime
from decimal import Decimal
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
def _num(value):
@@ -14,7 +14,7 @@ def _num(value):
return value
-class BackupRun(db.Model):
+class BackupRun(JsonColumnMixin, 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
@@ -76,15 +76,10 @@ class BackupRun(db.Model):
return level
def get_metadata(self):
- if not self.metadata_json:
- return {}
- try:
- return json.loads(self.metadata_json)
- except (json.JSONDecodeError, TypeError):
- return {}
+ return self._json_read('metadata_json')
def set_metadata(self, value):
- self.metadata_json = json.dumps(value or {})
+ self._json_write('metadata_json', value, falsy='{}')
def to_dict(self):
meta = self.get_metadata()
diff --git a/backend/app/models/chat_webhook.py b/backend/app/models/chat_webhook.py
index 178dd512..115687c9 100644
--- a/backend/app/models/chat_webhook.py
+++ b/backend/app/models/chat_webhook.py
@@ -11,14 +11,14 @@ Per kind, ``credentials_json`` holds:
- discord / slack / webhook : {'url': ..., 'secret': <optional HMAC secret>}
- telegram : {'chat_id': ..., 'bot_token': ...}
"""
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
from app.utils.crypto import decrypt_secret_safe
-class ChatWebhookConnection(db.Model):
+class ChatWebhookConnection(JsonColumnMixin, db.Model):
__tablename__ = 'chat_webhook_connections'
KINDS = ('discord', 'slack', 'telegram', 'webhook')
@@ -48,15 +48,11 @@ class ChatWebhookConnection(db.Model):
last_test_ok = db.Column(db.Boolean)
def raw_credentials(self):
- try:
- value = json.loads(self.credentials_json) if self.credentials_json else {}
- except (json.JSONDecodeError, TypeError):
- return {}
# A hand-edited or corrupt row can hold valid JSON of the wrong shape
# (``[]``, a string, ``null``). Every caller assumes a mapping, so
# normalise here rather than at each call site -- same guard as
# ``categories()`` below.
- return value if isinstance(value, dict) else {}
+ return self._json_read('credentials_json', expect=dict)
def credentials(self):
"""Decrypted credentials for use at send/test time (never serialized)."""
@@ -66,11 +62,7 @@ class ChatWebhookConnection(db.Model):
return out
def categories(self):
- try:
- value = json.loads(self.categories_json) if self.categories_json else []
- return value if isinstance(value, list) else []
- except (json.JSONDecodeError, TypeError):
- return []
+ return self._json_read('categories_json', [], expect=list)
def matches_category(self, category):
"""A connection with no category filter accepts everything."""
diff --git a/backend/app/models/deployment.py b/backend/app/models/deployment.py
index be1538b8..900217a2 100644
--- a/backend/app/models/deployment.py
+++ b/backend/app/models/deployment.py
@@ -10,10 +10,11 @@ Supports:
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
import json
-class Deployment(db.Model):
+class Deployment(JsonColumnMixin, db.Model):
"""Represents a single deployment of an application."""
__tablename__ = 'deployments'
@@ -63,10 +64,7 @@ class Deployment(db.Model):
def get_metadata(self):
"""Get metadata as dict."""
- try:
- return json.loads(self.extra_data) if self.extra_data else {}
- except (json.JSONDecodeError, TypeError):
- return {}
+ return self._json_read('extra_data')
def set_metadata(self, data):
"""Set metadata from dict."""
diff --git a/backend/app/models/deployment_snapshot.py b/backend/app/models/deployment_snapshot.py
index 74a32e75..4424daf2 100644
--- a/backend/app/models/deployment_snapshot.py
+++ b/backend/app/models/deployment_snapshot.py
@@ -15,12 +15,12 @@ git diffs). Snapshots are about *configuration*, not source files.
"""
from datetime import datetime
-import json
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class DeploymentSnapshot(db.Model):
+class DeploymentSnapshot(JsonColumnMixin, db.Model):
"""An immutable snapshot of an application's resolved configuration."""
__tablename__ = 'deployment_snapshots'
@@ -67,10 +67,7 @@ class DeploymentSnapshot(db.Model):
def get_config(self):
"""Return the parsed config dict (empty dict on any parse error)."""
- try:
- return json.loads(self.config_json) if self.config_json else {}
- except (json.JSONDecodeError, TypeError):
- return {}
+ return self._json_read('config_json')
def to_dict(self, include_config=True):
"""Convert to dictionary for API responses."""
diff --git a/backend/app/models/dns_cutover_snapshot.py b/backend/app/models/dns_cutover_snapshot.py
index a72758ef..a74aa57a 100644
--- a/backend/app/models/dns_cutover_snapshot.py
+++ b/backend/app/models/dns_cutover_snapshot.py
@@ -1,11 +1,11 @@
"""Reversible DNS cutover snapshot model."""
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class DnsCutoverSnapshot(db.Model):
+class DnsCutoverSnapshot(JsonColumnMixin, db.Model):
"""A point-in-time capture of a domain's live DNS records, taken right before
a migration cutover flips them to the new box (plan 27 Phase 6 #13, Decision 6).
@@ -45,28 +45,16 @@ class DnsCutoverSnapshot(db.Model):
applied_at = db.Column(db.DateTime, nullable=True)
def get_records(self):
- if not self.records_json:
- return []
- try:
- data = json.loads(self.records_json)
- return data if isinstance(data, list) else []
- except (json.JSONDecodeError, TypeError):
- return []
+ return self._json_read('records_json', [], expect=list)
def set_records(self, records):
- self.records_json = json.dumps(list(records or []))
+ self._json_write('records_json', list(records or []), falsy='[]')
def get_created_records(self):
- if not self.created_records_json:
- return []
- try:
- data = json.loads(self.created_records_json)
- return data if isinstance(data, list) else []
- except (json.JSONDecodeError, TypeError):
- return []
+ return self._json_read('created_records_json', [], expect=list)
def set_created_records(self, records):
- self.created_records_json = json.dumps(list(records or []))
+ self._json_write('created_records_json', list(records or []), falsy='[]')
def to_dict(self):
return {
diff --git a/backend/app/models/email_provider.py b/backend/app/models/email_provider.py
index 650e12ca..60620784 100644
--- a/backend/app/models/email_provider.py
+++ b/backend/app/models/email_provider.py
@@ -6,14 +6,14 @@ stored Fernet-encrypted (per-field) in ``credentials_json``; the public
``to_dict`` never exposes them. Follows the Connections pattern used by DNS /
cloud / registrar providers.
"""
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
from app.utils.crypto import decrypt_secret_safe
-class EmailProviderConnection(db.Model):
+class EmailProviderConnection(JsonColumnMixin, db.Model):
__tablename__ = 'email_provider_connections'
id = db.Column(db.Integer, primary_key=True)
@@ -43,10 +43,7 @@ class EmailProviderConnection(db.Model):
last_test_ok = db.Column(db.Boolean)
def raw_credentials(self):
- try:
- return json.loads(self.credentials_json) if self.credentials_json else {}
- except (json.JSONDecodeError, TypeError):
- return {}
+ return self._json_read('credentials_json')
def credentials(self):
"""Decrypted credentials for use at send/test time (never serialized)."""
diff --git a/backend/app/models/env_variable.py b/backend/app/models/env_variable.py
index 3bacdc10..1ba5f47d 100644
--- a/backend/app/models/env_variable.py
+++ b/backend/app/models/env_variable.py
@@ -1,12 +1,13 @@
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
from cryptography.fernet import Fernet
import os
import base64
import hashlib
-class EnvironmentVariable(db.Model):
+class EnvironmentVariable(JsonColumnMixin, db.Model):
"""
Stores environment variables for applications with encrypted values.
Supports versioning for history tracking.
@@ -83,17 +84,10 @@ class EnvironmentVariable(db.Model):
def get_reference(self):
"""Parsed value_from reference, or None for a plain value."""
- if not self.value_from:
- return None
- import json
- try:
- return json.loads(self.value_from)
- except Exception:
- return None
+ return self._json_read('value_from', None)
def set_reference(self, ref):
- import json
- self.value_from = json.dumps(ref) if ref else None
+ self._json_write('value_from', ref)
def to_dict(self, include_value=True, mask_secrets=False):
"""Convert to dictionary, optionally masking secret values."""
diff --git a/backend/app/models/error_log.py b/backend/app/models/error_log.py
index caa741dc..6cebe066 100644
--- a/backend/app/models/error_log.py
+++ b/backend/app/models/error_log.py
@@ -1,9 +1,9 @@
from datetime import datetime
from app import db
-import json
+from app.models.json_column_mixin import JsonColumnMixin
-class ErrorLog(db.Model):
+class ErrorLog(JsonColumnMixin, db.Model):
"""Centralized error log with fingerprint-based dedup."""
__tablename__ = 'error_logs'
@@ -28,19 +28,11 @@ class ErrorLog(db.Model):
def get_context(self):
"""Return parsed context JSON."""
- if self.context_json:
- try:
- return json.loads(self.context_json)
- except (json.JSONDecodeError, TypeError):
- return {}
- return {}
+ return self._json_read('context_json')
def set_context(self, context_dict):
"""Set context from a dictionary."""
- if context_dict:
- self.context_json = json.dumps(context_dict)
- else:
- self.context_json = None
+ self._json_write('context_json', context_dict)
def to_dict(self):
return {
diff --git a/backend/app/models/event_subscription.py b/backend/app/models/event_subscription.py
index 668574ca..a3ec87e5 100644
--- a/backend/app/models/event_subscription.py
+++ b/backend/app/models/event_subscription.py
@@ -1,11 +1,11 @@
"""Event subscription and delivery models for webhook system."""
from datetime import datetime
from app import db
-import json
+from app.models.json_column_mixin import JsonColumnMixin
import secrets
-class EventSubscription(db.Model):
+class EventSubscription(JsonColumnMixin, db.Model):
"""Webhook subscription for event notifications."""
__tablename__ = 'event_subscriptions'
@@ -33,29 +33,19 @@ class EventSubscription(db.Model):
def get_events(self):
"""Return parsed events list."""
- if self.events:
- try:
- return json.loads(self.events)
- except (json.JSONDecodeError, TypeError):
- return []
- return []
+ return self._json_read('events', [])
def set_events(self, events_list):
"""Set events from a list."""
- self.events = json.dumps(events_list) if events_list else '[]'
+ self._json_write('events', events_list, falsy='[]')
def get_headers(self):
"""Return parsed custom headers."""
- if self.headers:
- try:
- return json.loads(self.headers)
- except (json.JSONDecodeError, TypeError):
- return {}
- return {}
+ return self._json_read('headers')
def set_headers(self, headers_dict):
"""Set custom headers from a dict."""
- self.headers = json.dumps(headers_dict) if headers_dict else None
+ self._json_write('headers', headers_dict)
def matches_event(self, event_type):
"""Check if this subscription matches the given event type."""
@@ -90,7 +80,7 @@ class EventSubscription(db.Model):
return f'<EventSubscription {self.name} → {self.url}>'
-class EventDelivery(db.Model):
+class EventDelivery(JsonColumnMixin, db.Model):
"""Record of a webhook delivery attempt."""
__tablename__ = 'event_deliveries'
@@ -117,15 +107,10 @@ class EventDelivery(db.Model):
STATUS_FAILED = 'failed'
def get_payload(self):
- if self.payload:
- try:
- return json.loads(self.payload)
- except (json.JSONDecodeError, TypeError):
- return {}
- return {}
+ return self._json_read('payload')
def set_payload(self, payload_dict):
- self.payload = json.dumps(payload_dict) if payload_dict else None
+ self._json_write('payload', payload_dict)
def to_dict(self):
return {
diff --git a/backend/app/models/fleet_doctor_result.py b/backend/app/models/fleet_doctor_result.py
index 630eb2ac..4b57929b 100644
--- a/backend/app/models/fleet_doctor_result.py
+++ b/backend/app/models/fleet_doctor_result.py
@@ -1,11 +1,11 @@
"""Fleet-doctor per-server result model."""
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class FleetDoctorResult(db.Model):
+class FleetDoctorResult(JsonColumnMixin, db.Model):
"""One row per ``(server_id, check_key)`` recorded by the fleet health sweep
(Fleet Parity Sweep, plan 26 Phase 2, Decision 3).
@@ -45,15 +45,10 @@ class FleetDoctorResult(db.Model):
)
def get_repair_ref(self):
- if not self.repair_ref:
- return None
- try:
- return json.loads(self.repair_ref)
- except (json.JSONDecodeError, TypeError):
- return None
+ return self._json_read('repair_ref', None)
def set_repair_ref(self, ref):
- self.repair_ref = json.dumps(ref) if ref else None
+ self._json_write('repair_ref', ref)
def to_dict(self):
return {
diff --git a/backend/app/models/image_scan.py b/backend/app/models/image_scan.py
index ec02f482..6cb1a258 100644
--- a/backend/app/models/image_scan.py
+++ b/backend/app/models/image_scan.py
@@ -1,9 +1,10 @@
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
import json
-class ImageVulnerabilityScan(db.Model):
+class ImageVulnerabilityScan(JsonColumnMixin, db.Model):
"""CVE scan result for a Docker image used by an application."""
__tablename__ = 'image_vulnerability_scans'
@@ -25,23 +26,13 @@ class ImageVulnerabilityScan(db.Model):
self.severity_counts = json.dumps(counts)
def get_counts(self):
- if not self.severity_counts:
- return {}
- try:
- return json.loads(self.severity_counts)
- except Exception:
- return {}
+ return self._json_read('severity_counts')
def set_findings(self, findings):
- self.findings = json.dumps(findings) if findings else None
+ self._json_write('findings', findings)
def get_findings(self):
- if not self.findings:
- return []
- try:
- return json.loads(self.findings)
- except Exception:
- return []
+ return self._json_read('findings', [])
@property
def highest_severity(self):
diff --git a/backend/app/models/invitation.py b/backend/app/models/invitation.py
index 94a5014e..3a2a61c7 100644
--- a/backend/app/models/invitation.py
+++ b/backend/app/models/invitation.py
@@ -1,10 +1,10 @@
from datetime import datetime
from uuid import uuid4
from app import db
-import json
+from app.models.json_column_mixin import JsonColumnMixin
-class Invitation(db.Model):
+class Invitation(JsonColumnMixin, db.Model):
"""Team invitation model for invite-based registration."""
__tablename__ = 'invitations'
@@ -41,15 +41,10 @@ class Invitation(db.Model):
return self.status == self.STATUS_PENDING and not self.is_expired
def get_permissions(self):
- if self.permissions:
- try:
- return json.loads(self.permissions)
- except (json.JSONDecodeError, TypeError):
- return None
- return None
+ return self._json_read('permissions', None)
def set_permissions(self, perms_dict):
- self.permissions = json.dumps(perms_dict) if perms_dict else None
+ self._json_write('permissions', perms_dict)
def to_dict(self):
return {
diff --git a/backend/app/models/json_column_mixin.py b/backend/app/models/json_column_mixin.py
new file mode 100644
index 00000000..b0677ddc
--- /dev/null
+++ b/backend/app/models/json_column_mixin.py
@@ -0,0 +1,60 @@
+"""One implementation of the JSON-in-a-Text-column accessor pattern (plan 75 §F2).
+
+Dozens of models hand-roll the same pair over a ``db.Text`` column:
+
+ def get_details(self):
+ if self.details:
+ try:
+ return json.loads(self.details)
+ except (json.JSONDecodeError, TypeError):
+ return {}
+ return {}
+
+Every hand-rolled copy is a place a fix has to be made N times — the exact
+duplication this plan exists to remove. Models opt in by inheriting the mixin
+and delegating:
+
+ class AuditLog(JsonColumnMixin, db.Model):
+ def get_details(self):
+ return self._json_read('details')
+
+The per-model parts stay per-model: the accessor's *name* (``get_details`` vs
+``get_metadata``), the *column* it reads, and its *default*. What is
+consolidated is only the mechanics — empty-is-default, corrupt-is-default,
+optional shape check, falsy-on-write.
+
+Corrupt JSON reads as the default, never raises: a hand-edited or
+partially-written row must not 500 every endpoint that serializes the model.
+This is the dominant in-tree convention; the handful of models that let
+``json.loads`` raise on corrupt data are deliberately NOT converted (that
+would be a behaviour change, not a consolidation).
+"""
+import json
+
+_UNSET = object()
+
+
+class JsonColumnMixin:
+ """Helpers for models storing JSON in Text columns. See module docstring."""
+
+ def _json_read(self, column, default=_UNSET, expect=None):
+ """Parsed JSON from *column*, or *default* (``{}`` when omitted) when
+ the column is empty, unparseable, or — when *expect* is given — valid
+ JSON of the wrong shape (a corrupt ``[]`` where a mapping belongs)."""
+ fallback = {} if default is _UNSET else default
+ raw = getattr(self, column)
+ if not raw:
+ return fallback
+ try:
+ value = json.loads(raw)
+ except (json.JSONDecodeError, TypeError):
+ return fallback
+ if expect is not None and not isinstance(value, expect):
+ return fallback
+ return value
+
+ def _json_write(self, column, value, falsy=None):
+ """Serialize *value* into *column*; store *falsy* verbatim when *value*
+ is falsy (``None`` → NULL by default, ``'[]'``/``'{}'`` for columns
+ whose readers expect a container)."""
+ setattr(self, column, json.dumps(value) if value else falsy)
diff --git a/backend/app/models/managed_database_user.py b/backend/app/models/managed_database_user.py
index 7b697829..c16d1c76 100644
--- a/backend/app/models/managed_database_user.py
+++ b/backend/app/models/managed_database_user.py
@@ -1,10 +1,10 @@
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class ManagedDatabaseUser(db.Model):
+class ManagedDatabaseUser(JsonColumnMixin, db.Model):
"""A database user/grant ServerKit created on a managed database.
Live engines forget nothing, but ServerKit used to: users created through
@@ -45,14 +45,10 @@ class ManagedDatabaseUser(db.Model):
)
def get_grants(self):
- try:
- grants = json.loads(self.grants or '[]')
- return grants if isinstance(grants, list) else []
- except (ValueError, TypeError):
- return []
+ return self._json_read('grants', [], expect=list)
def set_grants(self, grants):
- self.grants = json.dumps(list(grants or []))
+ self._json_write('grants', list(grants or []), falsy='[]')
@property
def is_expired(self):
diff --git a/backend/app/models/notification_preferences.py b/backend/app/models/notification_preferences.py
index ee7295f7..26e81110 100644
--- a/backend/app/models/notification_preferences.py
+++ b/backend/app/models/notification_preferences.py
@@ -6,10 +6,11 @@ Stores per-user notification preferences for receiving alerts.
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
import json
-class NotificationPreferences(db.Model):
+class NotificationPreferences(JsonColumnMixin, db.Model):
__tablename__ = 'notification_preferences'
id = db.Column(db.Integer, primary_key=True)
@@ -59,10 +60,7 @@ class NotificationPreferences(db.Model):
def get_channels(self):
"""Get the list of enabled channels."""
- try:
- return json.loads(self.channels) if self.channels else ['email']
- except (json.JSONDecodeError, TypeError):
- return ['email']
+ return self._json_read('channels', ['email'])
def set_channels(self, channels_list):
"""Set the list of enabled channels."""
@@ -70,10 +68,7 @@ class NotificationPreferences(db.Model):
def get_severities(self):
"""Get the list of enabled severity levels."""
- try:
- return json.loads(self.severities) if self.severities else ['critical', 'warning']
- except (json.JSONDecodeError, TypeError):
- return ['critical', 'warning']
+ return self._json_read('severities', ['critical', 'warning'])
def set_severities(self, severities_list):
"""Set the list of enabled severity levels."""
@@ -81,15 +76,12 @@ class NotificationPreferences(db.Model):
def get_categories(self):
"""Get notification category preferences."""
- try:
- return json.loads(self.categories) if self.categories else {
- 'system': True,
- 'security': True,
- 'backups': True,
- 'apps': True
- }
- except (json.JSONDecodeError, TypeError):
- return {'system': True, 'security': True, 'backups': True, 'apps': True}
+ return self._json_read('categories', {
+ 'system': True,
+ 'security': True,
+ 'backups': True,
+ 'apps': True,
+ })
def set_categories(self, categories_dict):
"""Set notification category preferences."""
diff --git a/backend/app/models/passkey.py b/backend/app/models/passkey.py
index 9ba04034..f25c2283 100644
--- a/backend/app/models/passkey.py
+++ b/backend/app/models/passkey.py
@@ -1,7 +1,7 @@
-import json
import base64
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
def _b64decode_url(value: str) -> bytes:
@@ -14,7 +14,7 @@ def _b64decode_url(value: str) -> bytes:
return base64.urlsafe_b64decode(value)
-class PasskeyCredential(db.Model):
+class PasskeyCredential(JsonColumnMixin, db.Model):
"""Stored WebAuthn credential for a user."""
__tablename__ = 'passkey_credentials'
@@ -32,15 +32,10 @@ class PasskeyCredential(db.Model):
user = db.relationship('User', backref=db.backref('passkeys', lazy='dynamic'))
def get_transports(self):
- if not self.transports:
- return []
- try:
- return json.loads(self.transports)
- except Exception:
- return []
+ return self._json_read('transports', [])
def set_transports(self, transports):
- self.transports = json.dumps(list(transports)) if transports else None
+ self._json_write('transports', list(transports) if transports else None)
def to_dict(self):
return {
diff --git a/backend/app/models/proxy_stack.py b/backend/app/models/proxy_stack.py
index df52093f..ed5f0ddf 100644
--- a/backend/app/models/proxy_stack.py
+++ b/backend/app/models/proxy_stack.py
@@ -8,13 +8,13 @@ config snippet for one server. It is intentionally keyed 1:1 on server_id
(unique) — a server runs at most one managed proxy stack at a time.
"""
import uuid
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class ProxyStack(db.Model):
+class ProxyStack(JsonColumnMixin, db.Model):
"""One managed reverse-proxy stack per server."""
__tablename__ = 'proxy_stacks'
@@ -56,13 +56,7 @@ class ProxyStack(db.Model):
def networks_list(self):
"""Decode the networks JSON column to a list (empty on missing/bad)."""
- if not self.networks:
- return []
- try:
- data = json.loads(self.networks)
- return data if isinstance(data, list) else []
- except (TypeError, ValueError):
- return []
+ return self._json_read('networks', [], expect=list)
def to_dict(self):
return {
diff --git a/backend/app/models/restore_drill.py b/backend/app/models/restore_drill.py
index 709c2a89..dfd84ad0 100644
--- a/backend/app/models/restore_drill.py
+++ b/backend/app/models/restore_drill.py
@@ -1,10 +1,10 @@
-import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class RestoreDrill(db.Model):
+class RestoreDrill(JsonColumnMixin, db.Model):
"""A single restore *drill* — a real restore of a policy's latest restorable
point into a scratch location (temp dir / scratch DB), probe-verified, then
torn down. Never touches the live target.
@@ -43,15 +43,10 @@ class RestoreDrill(db.Model):
error = db.Column(db.Text, nullable=True)
def get_probes(self):
- if not self.probes_json:
- return {}
- try:
- return json.loads(self.probes_json)
- except (json.JSONDecodeError, TypeError):
- return {}
+ return self._json_read('probes_json')
def set_probes(self, value):
- self.probes_json = json.dumps(value or {})
+ self._json_write('probes_json', value, falsy='{}')
def to_dict(self):
return {
diff --git a/backend/app/models/sanitization_profile.py b/backend/app/models/sanitization_profile.py
index aa89e109..f9915078 100644
--- a/backend/app/models/sanitization_profile.py
+++ b/backend/app/models/sanitization_profile.py
@@ -8,10 +8,11 @@ between environments.
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
import json
-class SanitizationProfile(db.Model):
+class SanitizationProfile(JsonColumnMixin, db.Model):
"""Reusable database sanitization preset."""
__tablename__ = 'sanitization_profiles'
@@ -46,10 +47,7 @@ class SanitizationProfile(db.Model):
def get_config(self):
"""Parse and return the config dict."""
- try:
- return json.loads(self.config) if self.config else {}
- except (json.JSONDecodeError, TypeError):
- return {}
+ return self._json_read('config')
def set_config(self, config_dict):
"""Set config from a dict."""
diff --git a/backend/app/models/server.py b/backend/app/models/server.py
index d8023279..ab585ee8 100644
--- a/backend/app/models/server.py
+++ b/backend/app/models/server.py
@@ -3,6 +3,7 @@ import secrets
from datetime import datetime
from werkzeug.security import generate_password_hash, check_password_hash
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
class ServerGroup(db.Model):
@@ -50,7 +51,7 @@ class ServerGroup(db.Model):
return f'<ServerGroup {self.name}>'
-class Server(db.Model):
+class Server(JsonColumnMixin, db.Model):
"""Represents a remote server managed by ServerKit"""
__tablename__ = 'servers'
@@ -427,14 +428,7 @@ class Server(db.Model):
Returns an empty list when unset or malformed so the API/UI never
crash on legacy/partial data.
"""
- if not self.onboarding_progress:
- return []
- try:
- import json
- data = json.loads(self.onboarding_progress)
- return data if isinstance(data, list) else []
- except (TypeError, ValueError):
- return []
+ return self._json_read('onboarding_progress', [], expect=list)
# Emitted by to_dict but not mapped columns: each costs a relationship load
# or a JSON walk, so `$select` has to know they exist in order to decline
diff --git a/backend/app/models/system_event.py b/backend/app/models/system_event.py
index 498d6894..5c8b46f7 100644
--- a/backend/app/models/system_event.py
+++ b/backend/app/models/system_event.py
@@ -9,9 +9,10 @@ import json
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class SystemEvent(db.Model):
+class SystemEvent(JsonColumnMixin, db.Model):
"""A single event in the unified telemetry stream."""
__tablename__ = 'system_events'
@@ -83,12 +84,7 @@ class SystemEvent(db.Model):
def get_payload(self):
"""Return parsed payload JSON."""
- if self.payload_json:
- try:
- return json.loads(self.payload_json)
- except (json.JSONDecodeError, TypeError):
- return {}
- return {}
+ return self._json_read('payload_json')
def set_payload(self, payload_dict):
"""Set payload from a dictionary."""
diff --git a/backend/app/models/user.py b/backend/app/models/user.py
index 0ea6050c..27d56aa1 100644
--- a/backend/app/models/user.py
+++ b/backend/app/models/user.py
@@ -2,10 +2,11 @@ from datetime import datetime, timedelta
from sqlalchemy.orm import validates
from werkzeug.security import generate_password_hash, check_password_hash
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
import json
-class User(db.Model):
+class User(JsonColumnMixin, db.Model):
__tablename__ = 'users'
# Role constants
@@ -181,16 +182,12 @@ class User(db.Model):
def get_sidebar_config(self):
"""Return sidebar config dict, or default."""
- if self.sidebar_config:
- try:
- return json.loads(self.sidebar_config)
- except (json.JSONDecodeError, TypeError):
- pass
- return {'preset': 'full', 'hiddenItems': []}
+ return self._json_read('sidebar_config',
+ {'preset': 'full', 'hiddenItems': []})
def set_sidebar_config(self, config):
"""Store sidebar config as JSON."""
- self.sidebar_config = json.dumps(config) if config else None
+ self._json_write('sidebar_config', config)
def to_dict(self):
return {
@@ -214,12 +211,7 @@ class User(db.Model):
def get_backup_codes(self):
"""Get the list of backup code hashes."""
- if not self.backup_codes:
- return []
- try:
- return json.loads(self.backup_codes)
- except (json.JSONDecodeError, TypeError):
- return []
+ return self._json_read('backup_codes', [])
def set_backup_codes(self, codes_hashes):
"""Store backup code hashes."""
diff --git a/backend/app/models/waf_policy.py b/backend/app/models/waf_policy.py
index c69da0a3..8766dcc2 100644
--- a/backend/app/models/waf_policy.py
+++ b/backend/app/models/waf_policy.py
@@ -9,9 +9,10 @@ from datetime import datetime
import json
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class WafPolicy(db.Model):
+class WafPolicy(JsonColumnMixin, db.Model):
"""ModSecurity / OWASP CRS configuration for a single application."""
__tablename__ = 'waf_policies'
@@ -40,13 +41,7 @@ class WafPolicy(db.Model):
@property
def disabled_rules(self):
"""Return the disabled rule IDs as a list (empty list when unset)."""
- if not self.disabled_rule_ids:
- return []
- try:
- value = json.loads(self.disabled_rule_ids)
- return value if isinstance(value, list) else []
- except (ValueError, TypeError):
- return []
+ return self._json_read('disabled_rule_ids', [], expect=list)
@disabled_rules.setter
def disabled_rules(self, value):
diff --git a/backend/app/models/webhook_gateway.py b/backend/app/models/webhook_gateway.py
index 614e1810..abe3cfe8 100644
--- a/backend/app/models/webhook_gateway.py
+++ b/backend/app/models/webhook_gateway.py
@@ -4,9 +4,10 @@ import hashlib
import base64
from datetime import datetime
from app import db
+from app.models.json_column_mixin import JsonColumnMixin
-class WebhookEndpoint(db.Model):
+class WebhookEndpoint(JsonColumnMixin, db.Model):
"""Inbound webhook endpoint configuration."""
__tablename__ = 'webhook_endpoints'
@@ -27,15 +28,10 @@ class WebhookEndpoint(db.Model):
deliveries = db.relationship('WebhookDelivery', backref='endpoint', lazy='dynamic', cascade='all, delete-orphan')
def get_filter_paths(self):
- if not self.filter_paths:
- return []
- try:
- return json.loads(self.filter_paths)
- except Exception:
- return []
+ return self._json_read('filter_paths', [])
def set_filter_paths(self, paths):
- self.filter_paths = json.dumps(list(paths)) if paths else None
+ self._json_write('filter_paths', list(paths) if paths else None)
def verify_signature(self, payload: bytes, signature_header: str, algorithm: str = 'sha256') -> bool:
"""Verify HMAC-SHA1/SHA256 signature from header."""
@@ -65,7 +61,7 @@ class WebhookEndpoint(db.Model):
}
-class WebhookDelivery(db.Model):
+class WebhookDelivery(JsonColumnMixin, db.Model):
"""Log of an inbound webhook delivery."""
__tablename__ = 'webhook_deliveries'
@@ -83,15 +79,10 @@ class WebhookDelivery(db.Model):
completed_at = db.Column(db.DateTime, nullable=True)
def get_headers(self):
- if not self.headers:
- return {}
- try:
- return json.loads(self.headers)
- except Exception:
- return {}
+ return self._json_read('headers')
def set_headers(self, headers):
- self.headers = json.dumps(dict(headers)) if headers else None
+ self._json_write('headers', dict(headers) if headers else None)
def to_dict(self):
return {
diff --git a/backend/tests/test_json_column_mixin.py b/backend/tests/test_json_column_mixin.py
new file mode 100644
index 00000000..f4e5d82e
--- /dev/null
+++ b/backend/tests/test_json_column_mixin.py
@@ -0,0 +1,112 @@
+"""The JsonColumnMixin contract (plan 75 §F2).
+
+The mixin exists so the next fix to JSON-column handling lands in ONE place
+instead of twenty. These tests pin the semantics every converted model now
+shares: empty is the default, corrupt is the default (never a 500 on a
+hand-edited row), wrong-shape JSON is the default when a shape is declared,
+and falsy-on-write stores the column's empty form.
+"""
+
+from app.models.json_column_mixin import JsonColumnMixin
+
+
+class _Row(JsonColumnMixin):
+ def __init__(self, **cols):
+ for key, value in cols.items():
+ setattr(self, key, value)
+
+
+# --------------------------------------------------------------------------- #
+# Reads
+# --------------------------------------------------------------------------- #
+
+def test_valid_json_round_trips():
+ row = _Row(details='{"a": 1}')
+ assert row._json_read('details') == {'a': 1}
+
+
+def test_default_is_a_fresh_dict_each_call():
+ row = _Row(details=None)
+ first, second = row._json_read('details'), row._json_read('details')
+ assert first == second == {}
+ assert first is not second # no shared mutable default
+
+
+def test_explicit_default_is_used():
+ row = _Row(events=None)
+ assert row._json_read('events', []) == []
+
+
+def test_none_is_a_legitimate_default():
+ row = _Row(repair_ref=None)
+ assert row._json_read('repair_ref', None) is None
+
+
+def test_corrupt_json_reads_as_the_default_never_raises():
+ """A hand-edited row must not 500 every endpoint that serializes it."""
+ row = _Row(details='{"a": 1') # truncated
+ assert row._json_read('details') == {}
+
+
+def test_wrong_shape_reads_as_the_default_when_expect_is_set():
+ row = _Row(creds='["not", "a", "mapping"]')
+ assert row._json_read('creds', expect=dict) == {}
+ row2 = _Row(creds='{"ok": true}')
+ assert row2._json_read('creds', expect=dict) == {'ok': True}
+
+
+def test_expect_none_imposes_no_shape_check():
+ row = _Row(data='[1, 2]')
+ assert row._json_read('data') == [1, 2]
+
+
+# --------------------------------------------------------------------------- #
+# Writes
+# --------------------------------------------------------------------------- #
+
+def test_write_serializes_truthy_values():
+ row = _Row(details=None)
+ row._json_write('details', {'a': 1})
+ assert row.details == '{"a": 1}'
+
+
+def test_falsy_writes_null_by_default():
+ row = _Row(details='{"a": 1}')
+ row._json_write('details', {})
+ assert row.details is None
+
+
+def test_falsy_writes_the_columns_empty_form_when_declared():
+ row = _Row(events=None)
+ row._json_write('events', [], falsy='[]')
+ assert row.events == '[]'
+
+
+# --------------------------------------------------------------------------- #
+# The models actually opted in
+# --------------------------------------------------------------------------- #
+
+def test_converted_models_inherit_the_mixin():
+ """A model converted back to a hand-rolled copy is the second door
+ reopening — the plan's thesis. Pin the opt-in list."""
+ from app.models.audit_log import AuditLog
+ from app.models.backup_run import BackupRun
+ from app.models.user import User
+
+ for model in (AuditLog, BackupRun, User):
+ assert issubclass(model, JsonColumnMixin)
+
+
+def test_a_converted_model_end_to_end(app):
+ """Through the ORM, not just the mixin: corrupt column -> default."""
+ from app import db
+ from app.models.audit_log import AuditLog
+
+ entry = AuditLog(action='test.json_mixin', details='not json{')
+ db.session.add(entry)
+ db.session.commit()
+
+ assert entry.get_details() == {}
+ entry.set_details({'k': 'v'})
+ assert entry.details == '{"k": "v"}'
+ assert entry.get_details() == {'k': 'v'}