ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
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.pyindex 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 datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinimport hashlib-import jsonimport 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.pyindex 2953428b..4aff954c 100644--- a/backend/app/models/application_manifest.py+++ b/backend/app/models/application_manifest.py@@ -10,6 +10,7 @@ import jsonfrom datetime import datetimefrom 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 manifestSTATUS_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 Nonediff --git a/backend/app/models/application_preview.py b/backend/app/models/application_preview.pyindex 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 jsonfrom datetime import datetimefrom 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.pyindex bd256585..b945637a 100644--- a/backend/app/models/audit_log.py+++ b/backend/app/models/audit_log.py@@ -1,9 +1,9 @@from datetime import datetimefrom 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.pyindex 33e8422c..dddbbca7 100644--- a/backend/app/models/backup_policy.py+++ b/backend/app/models/backup_policy.py@@ -1,8 +1,8 @@-import jsonfrom datetime import datetimefrom decimal import Decimalfrom 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.pyindex a39012d8..6f065589 100644--- a/backend/app/models/backup_run.py+++ b/backend/app/models/backup_run.py@@ -1,8 +1,8 @@-import jsonfrom datetime import datetimefrom decimal import Decimalfrom app import db+from app.models.json_column_mixin import JsonColumnMixindef _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 leveldef 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.pyindex 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 jsonfrom datetime import datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinfrom 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 outdef 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.pyindex be1538b8..900217a2 100644--- a/backend/app/models/deployment.py+++ b/backend/app/models/deployment.py@@ -10,10 +10,11 @@ Supports:from datetime import datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinimport 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.pyindex 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 jsonfrom 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.pyindex 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 jsonfrom datetime import datetimefrom 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 beforea 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.pyindex 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 jsonfrom datetime import datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinfrom 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.pyindex 3bacdc10..1ba5f47d 100644--- a/backend/app/models/env_variable.py+++ b/backend/app/models/env_variable.py@@ -1,12 +1,13 @@from datetime import datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinfrom cryptography.fernet import Fernetimport osimport base64import 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.pyindex caa741dc..6cebe066 100644--- a/backend/app/models/error_log.py+++ b/backend/app/models/error_log.py@@ -1,9 +1,9 @@from datetime import datetimefrom 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.pyindex 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 datetimefrom app import db-import json+from app.models.json_column_mixin import JsonColumnMixinimport 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.pyindex 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 jsonfrom datetime import datetimefrom 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.pyindex ec02f482..6cb1a258 100644--- a/backend/app/models/image_scan.py+++ b/backend/app/models/image_scan.py@@ -1,9 +1,10 @@from datetime import datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinimport 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', [])@propertydef highest_severity(self):diff --git a/backend/app/models/invitation.py b/backend/app/models/invitation.pyindex 94a5014e..3a2a61c7 100644--- a/backend/app/models/invitation.py+++ b/backend/app/models/invitation.py@@ -1,10 +1,10 @@from datetime import datetimefrom uuid import uuid4from 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_expireddef 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.pynew file mode 100644index 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.pyindex 7b697829..c16d1c76 100644--- a/backend/app/models/managed_database_user.py+++ b/backend/app/models/managed_database_user.py@@ -1,10 +1,10 @@-import jsonfrom datetime import datetimefrom 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='[]')@propertydef is_expired(self):diff --git a/backend/app/models/notification_preferences.py b/backend/app/models/notification_preferences.pyindex 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 datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinimport 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.pyindex 9ba04034..f25c2283 100644--- a/backend/app/models/passkey.py+++ b/backend/app/models/passkey.py@@ -1,7 +1,7 @@-import jsonimport base64from datetime import datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixindef _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.pyindex 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 jsonfrom datetime import datetimefrom 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.pyindex 709c2a89..dfd84ad0 100644--- a/backend/app/models/restore_drill.py+++ b/backend/app/models/restore_drill.py@@ -1,10 +1,10 @@-import jsonfrom datetime import datetimefrom 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 restorablepoint into a scratch location (temp dir / scratch DB), probe-verified, thentorn 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.pyindex 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 datetimefrom app import db+from app.models.json_column_mixin import JsonColumnMixinimport 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.pyindex d8023279..ab585ee8 100644--- a/backend/app/models/server.py+++ b/backend/app/models/server.py@@ -3,6 +3,7 @@ import secretsfrom datetime import datetimefrom werkzeug.security import generate_password_hash, check_password_hashfrom app import db+from app.models.json_column_mixin import JsonColumnMixinclass 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 nevercrash 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 declinediff --git a/backend/app/models/system_event.py b/backend/app/models/system_event.pyindex 498d6894..5c8b46f7 100644--- a/backend/app/models/system_event.py+++ b/backend/app/models/system_event.py@@ -9,9 +9,10 @@ import jsonfrom datetime import datetimefrom 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.pyindex 0ea6050c..27d56aa1 100644--- a/backend/app/models/user.py+++ b/backend/app/models/user.py@@ -2,10 +2,11 @@ from datetime import datetime, timedeltafrom sqlalchemy.orm import validatesfrom werkzeug.security import generate_password_hash, check_password_hashfrom app import db+from app.models.json_column_mixin import JsonColumnMixinimport 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.pyindex c69da0a3..8766dcc2 100644--- a/backend/app/models/waf_policy.py+++ b/backend/app/models/waf_policy.py@@ -9,9 +9,10 @@ from datetime import datetimeimport jsonfrom 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):@propertydef 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.setterdef disabled_rules(self, value):diff --git a/backend/app/models/webhook_gateway.py b/backend/app/models/webhook_gateway.pyindex 614e1810..abe3cfe8 100644--- a/backend/app/models/webhook_gateway.py+++ b/backend/app/models/webhook_gateway.py@@ -4,9 +4,10 @@ import hashlibimport base64from datetime import datetimefrom 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.pynew file mode 100644index 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'}