Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(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__.py
index 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 FleetDoctorResult
from app.models.server_survey import ServerSurvey
from app.models.dns_cutover_snapshot import DnsCutoverSnapshot
from 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.py
new file mode 100644
index 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__.py
index 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.py
new file mode 100644
index 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.py
index 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_lifecycle
extension_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.py
new file mode 100644
index 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.py
new file mode 100644
index 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'