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
feat(models): canonical status vocabulary + RunLifecycleMixin (plan 77 D1/D2)
Juan Denis1b49352f2764
diff --git a/backend/app/models/mixins.py b/backend/app/models/mixins.pyindex 4b0410ab..5f066a38 100644--- a/backend/app/models/mixins.py+++ b/backend/app/models/mixins.py@@ -31,6 +31,7 @@ import uuidfrom datetime import datetimefrom app import db+from app.models import status as _statuslogger = logging.getLogger(__name__)@@ -196,3 +197,61 @@ class TimestampMixin:def updated_at(cls): # noqa: N805return db.Column(db.DateTime, default=datetime.utcnow,onupdate=datetime.utcnow)+++class RunLifecycleMixin:+ """State transitions for run-shaped models (plan 77 D2).++ Ten run models hand-write ``status`` + ``started_at``/``completed_at``+ (+ duration) transitions today; this mixin is the one place they happen::++ job.mark_running()+ job.mark_succeeded() # or mark_failed(error=...), mark_cancelled()++ Status spellings come from models/status.py. A domain still storing a+ legacy spelling (e.g. deployment jobs' 'succeeded') overrides the class+ attributes below until its per-domain data migration lands — adoption+ must NOT silently change stored strings.++ Column-name variance is absorbed, not forced: completed-at goes to+ ``__completed_at_attr__`` (default 'completed_at'; set 'finished_at'+ where that is the column), and a duration is stored only when the model+ actually has a 'duration_seconds' or 'duration' COLUMN (properties are+ left alone).+ """++ __status_running__ = _status.RUNNING+ __status_success__ = _status.SUCCESS+ __status_failed__ = _status.FAILED+ __status_cancelled__ = _status.CANCELLED+ __completed_at_attr__ = 'completed_at'++ def mark_running(self, when=None):+ self.status = self.__status_running__+ self.started_at = when or datetime.utcnow()+ return self++ def mark_succeeded(self, when=None):+ return self._finish(self.__status_success__, when)++ def mark_failed(self, error=None, when=None):+ self._finish(self.__status_failed__, when)+ if error is not None and 'error' in self.__table__.columns:+ self.error = str(error)+ return self++ def mark_cancelled(self, when=None):+ return self._finish(self.__status_cancelled__, when)++ def _finish(self, status, when=None):+ when = when or datetime.utcnow()+ self.status = status+ if self.__completed_at_attr__ in self.__table__.columns:+ setattr(self, self.__completed_at_attr__, when)+ started = getattr(self, 'started_at', None)+ if started is not None:+ for dattr in ('duration_seconds', 'duration'):+ if dattr in self.__table__.columns:+ setattr(self, dattr, (when - started).total_seconds())+ break+ return selfdiff --git a/backend/app/models/status.py b/backend/app/models/status.pynew file mode 100644index 00000000..222ffe27--- /dev/null+++ b/backend/app/models/status.py@@ -0,0 +1,59 @@+"""The ONE status vocabulary for run-shaped models (plan 77 D1).++The same terminal state has historically been spelled four ways across run+models (``success`` in cron_run/backup_run, ``completed`` in db_snapshot and+environment_activity, ``done`` in sandbox runs, ``succeeded`` in deployment+jobs). New columns and API filters import these constants; existing domains+keep their stored spelling until their own per-domain data migration lands+(changing stored strings wholesale is explicitly out of scope — each domain+migrates deliberately, smallest tables first) and normalize at the read edge+via :func:`normalize`.++RunLifecycleMixin (models/mixins.py) writes these constants for adopters,+with per-model overrides for domains still on a legacy spelling.+"""++PENDING = 'pending'+QUEUED = 'queued'+RUNNING = 'running'+SUCCESS = 'success'+FAILED = 'failed'+CANCELLED = 'cancelled'++#: States a run can never leave.+TERMINAL = frozenset({SUCCESS, FAILED, CANCELLED})++#: States describing a run that has not finished.+ACTIVE = frozenset({PENDING, QUEUED, RUNNING})++ALL = frozenset({PENDING, QUEUED, RUNNING, SUCCESS, FAILED, CANCELLED})++#: Every legacy spelling measured in the 2026-08-18 audit, mapped to its+#: canonical constant. Domain-specific *phase* states (``analyzing``,+#: ``verifying``, ``rolled_back``, …) are not lifecycle spellings and pass+#: through :func:`normalize` unchanged.+LEGACY_ALIASES = {+ 'succeeded': SUCCESS,+ 'completed': SUCCESS,+ 'done': SUCCESS,+ 'failure': FAILED,+ 'error': FAILED,+ 'canceled': CANCELLED,+ 'scheduled': QUEUED,+}+++def normalize(value):+ """Map a stored status string to its canonical spelling.++ Canonical values and unknown domain-specific states return unchanged;+ only known legacy aliases are rewritten. ``None`` stays ``None``.+ """+ if not value:+ return value+ return LEGACY_ALIASES.get(value, value)+++def is_terminal(value) -> bool:+ """True when the (possibly legacy-spelled) status is a terminal state."""+ return normalize(value) in TERMINALdiff --git a/backend/tests/test_status_vocabulary.py b/backend/tests/test_status_vocabulary.pynew file mode 100644index 00000000..5246d7dc--- /dev/null+++ b/backend/tests/test_status_vocabulary.py@@ -0,0 +1,90 @@+"""Plan 77 D1/D2 — canonical status vocabulary + run lifecycle transitions.++Parity gate: every status spelling a run model writes today is either a+canonical constant or a known legacy alias that normalize() maps home.+"""+import pytest++from app.models import status as st+++MEASURED_LIFECYCLE_SPELLINGS = {+ # canonical+ 'pending', 'queued', 'running', 'success', 'failed', 'cancelled',+ # legacy terminal spellings measured across run models (2026-08-18 audit)+ 'succeeded', 'completed', 'done', 'failure', 'error', 'canceled',+ 'scheduled',+}+++def test_every_measured_lifecycle_spelling_normalizes_to_canonical():+ for spelling in MEASURED_LIFECYCLE_SPELLINGS:+ assert st.normalize(spelling) in st.ALL, spelling+++def test_terminal_set_and_aliases():+ assert st.is_terminal('succeeded')+ assert st.is_terminal('done')+ assert st.is_terminal('failure')+ assert not st.is_terminal('running')+ assert not st.is_terminal('analyzing') # domain phase, passes through+++def test_normalize_passes_domain_states_through():+ assert st.normalize('rolled_back') == 'rolled_back'+ assert st.normalize(None) is None+ assert st.normalize('') == ''+++def test_run_lifecycle_mixin_transitions(app):+ from app import db+ from app.models.mixins import RunLifecycleMixin++ class _FakeRun(RunLifecycleMixin):+ # stand-in with the standard columns; __table__ faked via a dict+ class _T:+ columns = {'status': None, 'started_at': None,+ 'completed_at': None, 'duration_seconds': None,+ 'error': None}+ __table__ = _T()+ status = None+ started_at = None+ completed_at = None+ duration_seconds = None+ error = None++ run = _FakeRun()+ run.mark_running()+ assert run.status == st.RUNNING and run.started_at is not None++ run.mark_succeeded()+ assert run.status == st.SUCCESS+ assert run.completed_at is not None+ assert run.duration_seconds is not None and run.duration_seconds >= 0++ run2 = _FakeRun()+ run2.mark_running()+ run2.mark_failed(error='boom')+ assert run2.status == st.FAILED and run2.error == 'boom'++ run3 = _FakeRun()+ run3.mark_cancelled()+ assert run3.status == st.CANCELLED+++def test_legacy_spelling_override(app):+ from app.models.mixins import RunLifecycleMixin++ class _LegacyRun(RunLifecycleMixin):+ __status_success__ = 'succeeded' # domain not yet data-migrated+ class _T:+ columns = {'status': None, 'completed_at': None}+ __table__ = _T()+ status = None+ started_at = None+ completed_at = None++ run = _LegacyRun()+ run.mark_succeeded()+ assert run.status == 'succeeded'+ assert st.normalize(run.status) == st.SUCCESS