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(plugins): give extensions a place to keep their own state
Juan Deniscaa511064da7
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.pyindex 66507dca..9d8b3058 100644--- a/backend/app/models/__init__.py+++ b/backend/app/models/__init__.py@@ -80,6 +80,7 @@ from app.models.fleet_doctor_result import FleetDoctorResultfrom app.models.server_survey import ServerSurveyfrom app.models.dns_cutover_snapshot import DnsCutoverSnapshotfrom app.models.theme import Theme+from app.models.plugin_store import PluginStore__all__ = ['User', 'Application', 'Domain', 'EnvironmentVariable', 'EnvironmentVariableHistory',@@ -131,4 +132,5 @@ __all__ = ['ServerSurvey','DnsCutoverSnapshot','Theme',+ 'PluginStore',]diff --git a/backend/app/models/plugin_store.py b/backend/app/models/plugin_store.pynew file mode 100644index 00000000..7890b32e--- /dev/null+++ b/backend/app/models/plugin_store.py@@ -0,0 +1,54 @@+"""Per-plugin key/value storage.++An extension that needed to remember anything previously had to add a model to+core plus an Alembic migration — which is why extension tables like+``ext_serverkit_minecraft_*`` live in the core migration history. That is a+steep tax on small extensions and it puts plugin schema in the panel's own+upgrade path.++One row here is one key for one plugin. ``value`` is a native JSON column (the+dominant pattern in this codebase, and dialect-agnostic across SQLite and+PostgreSQL), so a plugin stores dicts, lists and scalars without serialising by+hand. Keys are opaque to the panel; namespace inside your own key space+(``world:1:seed``) if you want structure.++This does NOT replace ``InstalledPlugin.config``: config is panel-owned settings+an admin edits from the Marketplace, whereas the store is the plugin's own+state, written at runtime by the plugin itself.+"""++from datetime import datetime++from app import db+++class PluginStore(db.Model):+ """One key/value pair belonging to one installed plugin."""++ __tablename__ = 'plugin_store'++ id = db.Column(db.Integer, primary_key=True)+ # Not a ForeignKey to installed_plugins: rows must survive the plugin row+ # being deleted and re-created by a reinstall, which is the whole point of+ # keeping data across an uninstall that wasn't asked to purge.+ plugin_slug = db.Column(db.String(128), nullable=False, index=True)+ key = db.Column(db.String(255), nullable=False)+ value = db.Column(db.JSON)++ created_at = db.Column(db.DateTime, default=datetime.utcnow)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ __table_args__ = (+ db.UniqueConstraint('plugin_slug', 'key', name='uq_plugin_store_slug_key'),+ )++ def to_dict(self):+ return {+ 'plugin_slug': self.plugin_slug,+ 'key': self.key,+ 'value': self.value,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<PluginStore {self.plugin_slug}:{self.key}>'diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.pyindex 76811942..cf6ae0b3 100644--- a/backend/app/plugins_sdk/__init__.py+++ b/backend/app/plugins_sdk/__init__.py@@ -103,6 +103,7 @@ jobs = JobsSdk()_LAZY_SURFACES = {'deploys': ('app.plugins_sdk.deploys_sdk', 'deploys'),'search': ('app.plugins_sdk.search_sdk', 'search'),+ 'store': ('app.plugins_sdk.store_sdk', 'store'),}_lazy_cache = {}@@ -144,6 +145,7 @@ __all__ = ['jobs','deploys','search',+ 'store','permissions','require_permission','panel_version',diff --git a/backend/app/plugins_sdk/store_sdk.py b/backend/app/plugins_sdk/store_sdk.pynew file mode 100644index 00000000..056414f3--- /dev/null+++ b/backend/app/plugins_sdk/store_sdk.py@@ -0,0 +1,185 @@+"""Plugin-facing SDK for per-plugin state.++ from app.plugins_sdk import store++ mine = store.for_plugin('serverkit-minecraft')+ mine.set('world:1:seed', 8675309)+ seed = mine.get('world:1:seed')+ mine.delete('world:1:seed')++Use this instead of adding a model and a migration to core for every small+thing an extension needs to remember. Values are JSON — dicts, lists, strings,+numbers, booleans, None — persisted in one shared table, namespaced by slug so+two plugins can never collide on a key.++Reach for a real table (a declared ``ext_<slug>_*`` model) when you need to+query BY the data rather than by key: relations, ordering, aggregates, or more+rows than you would ever want to load at once. This is a key/value store, not a+database, and it will not save you from either.++Rows survive an ordinary uninstall — a reinstall finds its state where it left+it — and are deleted when the operator uninstalls *and* asks to purge data,+matching how extension-declared tables are treated.+"""++import json++from app import db+from app.models.plugin_store import PluginStore++#: Serialized-size ceiling for one value. The table is shared by every+#: installed plugin, so one of them cannot be allowed to put a hundred+#: megabytes in it — and a value that big wants a file or a table, not a key.+MAX_VALUE_BYTES = 256 * 1024++_MISSING = object()+++class PluginStoreError(ValueError):+ """A value or key the store refuses to persist."""+++class BoundStore:+ """The store as seen by one plugin. Get it from ``store.for_plugin()``."""++ def __init__(self, slug):+ if not slug or not isinstance(slug, str):+ raise PluginStoreError('a plugin store needs a plugin slug')+ self.slug = slug++ # ------------------------------------------------------------------ read+ def get(self, key, default=None):+ """The value stored at *key*, or *default* if nothing is stored."""+ row = self._row(key)+ return default if row is None else row.value++ def has(self, key):+ """True if *key* is set — distinguishes a stored ``None`` from absence."""+ return self._row(key) is not None++ def keys(self, prefix=None):+ """This plugin's keys, sorted; optionally only those under *prefix*."""+ query = PluginStore.query.filter_by(plugin_slug=self.slug)+ if prefix:+ query = query.filter(PluginStore.key.like(f'{_escape_like(prefix)}%',+ escape='\\'))+ return sorted(row.key for row in query.all())++ def all(self, prefix=None):+ """Every key/value this plugin has stored, as a dict."""+ query = PluginStore.query.filter_by(plugin_slug=self.slug)+ if prefix:+ query = query.filter(PluginStore.key.like(f'{_escape_like(prefix)}%',+ escape='\\'))+ return {row.key: row.value for row in query.all()}++ # ----------------------------------------------------------------- write+ def set(self, key, value):+ """Store *value* at *key*, replacing anything already there."""+ key = _clean_key(key)+ _check_value(value)++ row = self._row(key)+ if row is not None:+ row.value = value+ db.session.commit()+ return value++ db.session.add(PluginStore(plugin_slug=self.slug, key=key, value=value))+ try:+ db.session.commit()+ except Exception:+ # Another writer inserted the same key between the read and the+ # commit. The unique constraint is what makes that safe; take their+ # row and apply our write to it rather than failing the caller.+ db.session.rollback()+ row = self._row(key)+ if row is None:+ raise+ row.value = value+ db.session.commit()+ return value++ def setdefault(self, key, value):+ """Store *value* only if *key* is unset; return whatever is stored."""+ existing = self.get(key, _MISSING)+ if existing is not _MISSING:+ return existing+ return self.set(key, value)++ def delete(self, key):+ """Remove *key*. True if something was removed."""+ row = self._row(key)+ if row is None:+ return False+ db.session.delete(row)+ db.session.commit()+ return True++ def clear(self):+ """Remove everything this plugin has stored. Returns the row count."""+ return purge(self.slug)++ # --------------------------------------------------------------- helpers+ def _row(self, key):+ return PluginStore.query.filter_by(+ plugin_slug=self.slug, key=_clean_key(key)).first()+++class StoreSdk:+ """Stable storage surface for plugins."""++ def for_plugin(self, slug):+ """The store belonging to *slug*."""+ return BoundStore(slug)++ def purge(self, slug):+ """Delete every row belonging to *slug*. Returns the row count."""+ return purge(slug)+++def purge(slug):+ """Delete every stored row for *slug*; returns how many were removed.++ Called by the uninstaller, and available to a plugin's own teardown.+ """+ if not slug:+ return 0+ removed = PluginStore.query.filter_by(plugin_slug=slug).delete(+ synchronize_session=False)+ db.session.commit()+ return removed+++def _clean_key(key):+ if not isinstance(key, str) or not key.strip():+ raise PluginStoreError('store keys must be non-empty strings')+ key = key.strip()+ if len(key) > 255:+ raise PluginStoreError('store keys are limited to 255 characters')+ return key+++def _check_value(value):+ """Refuse a value the column can't hold, with a message that says why.++ Without this the failure surfaces as an opaque error at commit time — after+ the session is already poisoned, and usually far from the offending call.+ """+ try:+ encoded = json.dumps(value)+ except (TypeError, ValueError) as exc:+ raise PluginStoreError(f'store values must be JSON-serializable: {exc}') from exc+ if len(encoded.encode('utf-8')) > MAX_VALUE_BYTES:+ raise PluginStoreError(+ f'store value is larger than {MAX_VALUE_BYTES // 1024} KB — '+ 'keep bulk data in a file or a table of your own')+++def _escape_like(prefix):+ """Escape LIKE wildcards so a prefix containing % or _ matches literally."""+ return (str(prefix).replace('\\', '\\\\')+ .replace('%', '\\%').replace('_', '\\_'))+++store = StoreSdk()diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.pyindex 00865e5b..7a0ad587 100644--- a/backend/app/services/plugin_service.py+++ b/backend/app/services/plugin_service.py@@ -1306,12 +1306,19 @@ def uninstall_plugin(plugin_id, purge=False):# purge data. Best effort — never block teardown._run_lifecycle_hook(plugin, manifest, 'uninstall', purge=purge)- # Tear down declarative schedules, and (only on purge) the data tables.+ # Tear down declarative schedules, and (only on purge) the data tables and+ # the plugin's key/value store. Store rows follow the same rule as the+ # ext_* tables: an ordinary uninstall leaves them, so a reinstall finds its+ # state where it left it, and "uninstall and delete data" removes them.try:from app.services import extension_lifecycleextension_lifecycle.remove_jobs(plugin, manifest)if purge:extension_lifecycle.purge_models(plugin)+ from app.plugins_sdk.store_sdk import purge as purge_store+ removed = purge_store(slug)+ if removed:+ logger.info(f'Purged {removed} store row(s) for {slug}')except Exception as e:logger.warning(f'Extension lifecycle teardown for {slug}: {e}')diff --git a/backend/migrations/versions/079_plugin_store.py b/backend/migrations/versions/079_plugin_store.pynew file mode 100644index 00000000..3a0a25e6--- /dev/null+++ b/backend/migrations/versions/079_plugin_store.py@@ -0,0 +1,48 @@+"""Per-plugin key/value store.++Gives an extension somewhere to keep its own state without adding a model and a+migration to core for every small thing it needs to remember. One row is one key+for one plugin; the value is a native JSON column, which SQLAlchemy renders as+JSON on PostgreSQL and TEXT on SQLite.++Idempotent: guards on table presence like the other migrations here.++Revision ID: 079_plugin_store+Revises: 078_themes+Create Date: 2026-07-25+"""+from alembic import op+import sqlalchemy as sa++revision = '079_plugin_store'+down_revision = '078_themes'+branch_labels = None+depends_on = None+++def upgrade():+ conn = op.get_bind()+ inspector = sa.inspect(conn)+ if 'plugin_store' in set(inspector.get_table_names()):+ return+ op.create_table(+ 'plugin_store',+ sa.Column('id', sa.Integer(), nullable=False),+ sa.Column('plugin_slug', sa.String(length=128), nullable=False),+ sa.Column('key', sa.String(length=255), nullable=False),+ sa.Column('value', sa.JSON(), nullable=True),+ sa.Column('created_at', sa.DateTime(), nullable=True),+ sa.Column('updated_at', sa.DateTime(), nullable=True),+ sa.PrimaryKeyConstraint('id'),+ sa.UniqueConstraint('plugin_slug', 'key', name='uq_plugin_store_slug_key'),+ )+ op.create_index('ix_plugin_store_plugin_slug', 'plugin_store', ['plugin_slug'])+++def downgrade():+ conn = op.get_bind()+ inspector = sa.inspect(conn)+ if 'plugin_store' not in set(inspector.get_table_names()):+ return+ op.drop_index('ix_plugin_store_plugin_slug', table_name='plugin_store')+ op.drop_table('plugin_store')diff --git a/backend/tests/test_plugin_store_sdk.py b/backend/tests/test_plugin_store_sdk.pynew file mode 100644index 00000000..a395532b--- /dev/null+++ b/backend/tests/test_plugin_store_sdk.py@@ -0,0 +1,177 @@+"""Per-plugin key/value storage (plugins_sdk.store).++The tax this removes: before it, an extension that needed to remember anything+had to add a model AND an Alembic migration to core — which is why extension+tables sit in the panel's own migration history.++What the tests pin down is the part a shared table makes load-bearing: two+plugins can never see or clobber each other's keys, one plugin can't fill the+table, and an uninstall that wasn't asked to purge leaves the data alone.+"""++import pytest++from app import db+from app.models.plugin_store import PluginStore+from app.plugins_sdk.store_sdk import MAX_VALUE_BYTES, PluginStoreError, store+++def mine(app):+ return store.for_plugin('serverkit-demo')+++class TestRoundTrip:+ def test_set_then_get(self, app, mine):+ mine.set('world:1:seed', 8675309)+ assert mine.get('world:1:seed') == 8675309++ def test_stores_json_shapes(self, app, mine):+ value = {'players': ['a', 'b'], 'settings': {'hardcore': True, 'slots': 20},+ 'motd': None}+ mine.set('world:1', value)+ assert mine.get('world:1') == value++ def test_missing_key_returns_the_default(self, app, mine):+ assert mine.get('nope') is None+ assert mine.get('nope', 'fallback') == 'fallback'++ def test_has_distinguishes_a_stored_none_from_absence(self, app, mine):+ mine.set('explicit', None)+ # get() alone can't tell these apart, which is why has() exists.+ assert mine.get('explicit') is None and mine.get('absent') is None+ assert mine.has('explicit') is True+ assert mine.has('absent') is False++ def test_set_overwrites_without_duplicating_the_row(self, app, mine):+ mine.set('k', 'first')+ mine.set('k', 'second')+ assert mine.get('k') == 'second'+ assert PluginStore.query.filter_by(plugin_slug='serverkit-demo',+ key='k').count() == 1++ def test_setdefault_only_writes_when_unset(self, app, mine):+ assert mine.setdefault('k', 'original') == 'original'+ assert mine.setdefault('k', 'ignored') == 'original'++ def test_delete(self, app, mine):+ mine.set('k', 1)+ assert mine.delete('k') is True+ assert mine.delete('k') is False+ assert mine.get('k') is None++ def test_keys_and_all_with_a_prefix(self, app, mine):+ mine.set('world:1:seed', 1)+ mine.set('world:2:seed', 2)+ mine.set('backup:last', 3)++ assert mine.keys() == ['backup:last', 'world:1:seed', 'world:2:seed']+ assert mine.keys(prefix='world:') == ['world:1:seed', 'world:2:seed']+ assert mine.all(prefix='world:') == {'world:1:seed': 1, 'world:2:seed': 2}++ def test_prefix_wildcards_are_matched_literally(self, app, mine):+ # '_' and '%' are LIKE wildcards; an unescaped prefix would match keys+ # the caller never asked for.+ mine.set('a_b', 'wanted')+ mine.set('axb', 'not wanted')+ assert mine.keys(prefix='a_') == ['a_b']+++class TestIsolation:+ def test_two_plugins_cannot_see_or_clobber_each_other(self, app):+ one = store.for_plugin('plugin-one')+ two = store.for_plugin('plugin-two')++ one.set('shared-key', 'from one')+ two.set('shared-key', 'from two')++ assert one.get('shared-key') == 'from one'+ assert two.get('shared-key') == 'from two'+ assert one.keys() == ['shared-key']++ one.clear()+ assert one.get('shared-key') is None+ assert two.get('shared-key') == 'from two'+++class TestRefusals:+ def test_rejects_unserialisable_values(self, app, mine):+ # Caught at set() rather than at commit, where the error is opaque and+ # the session is already poisoned.+ with pytest.raises(PluginStoreError):+ mine.set('k', object())++ def test_rejects_oversized_values(self, app, mine):+ with pytest.raises(PluginStoreError):+ mine.set('k', 'x' * (MAX_VALUE_BYTES + 1))++ def test_rejects_empty_keys(self, app, mine):+ for key in ('', ' ', None, 7):+ with pytest.raises(PluginStoreError):+ mine.set(key, 1)++ def test_rejects_overlong_keys(self, app, mine):+ with pytest.raises(PluginStoreError):+ mine.set('k' * 256, 1)++ def test_a_store_needs_a_slug(self, app):+ with pytest.raises(PluginStoreError):+ store.for_plugin('')++ def test_a_refused_value_leaves_the_session_usable(self, app, mine):+ with pytest.raises(PluginStoreError):+ mine.set('k', object())+ # The point of validating early: the next write still works.+ mine.set('k', 'fine')+ assert mine.get('k') == 'fine'+++class TestUninstall:+ def _install_row(self, slug):+ from app.models.plugin import InstalledPlugin+ plugin = InstalledPlugin(slug=slug, name=slug, display_name=slug,+ version='1.0.0',+ status=InstalledPlugin.STATUS_ACTIVE)+ db.session.add(plugin)+ db.session.commit()+ return plugin++ def test_purge_removes_only_that_plugins_rows(self, app):+ store.for_plugin('plugin-one').set('k', 1)+ store.for_plugin('plugin-two').set('k', 2)++ assert store.purge('plugin-one') == 1+ assert store.for_plugin('plugin-one').get('k') is None+ assert store.for_plugin('plugin-two').get('k') == 2++ def test_uninstall_with_purge_clears_the_store(self, app, tmp_path, monkeypatch):+ from app.services import plugin_service++ plugin = self._install_row('demo-purge')+ store.for_plugin('demo-purge').set('k', 'data')+ monkeypatch.setattr(plugin_service, 'BACKEND_PLUGINS_DIR', str(tmp_path / 'b'))+ monkeypatch.setattr(plugin_service, 'FRONTEND_PLUGINS_DIR', str(tmp_path / 'f'))++ plugin_service.uninstall_plugin(plugin.id, purge=True)++ assert store.for_plugin('demo-purge').get('k') is None++ def test_uninstall_without_purge_keeps_the_store(self, app, tmp_path, monkeypatch):+ # Same rule the ext_* tables follow: reinstalling finds its state.+ from app.services import plugin_service++ plugin = self._install_row('demo-keep')+ store.for_plugin('demo-keep').set('k', 'data')+ monkeypatch.setattr(plugin_service, 'BACKEND_PLUGINS_DIR', str(tmp_path / 'b'))+ monkeypatch.setattr(plugin_service, 'FRONTEND_PLUGINS_DIR', str(tmp_path / 'f'))++ plugin_service.uninstall_plugin(plugin.id, purge=False)++ assert store.for_plugin('demo-keep').get('k') == 'data'+++def test_sdk_is_reachable_from_the_package(app):+ from app import plugins_sdk++ plugins_sdk.store.for_plugin('serverkit-demo').set('k', 'v')+ assert plugins_sdk.store.for_plugin('serverkit-demo').get('k') == 'v'