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): let extensions put their objects in global search

Juan Denis2a0b4ca02975
diff --git a/backend/app/plugins_sdk/__init__.py b/backend/app/plugins_sdk/__init__.py
index 5da80134..76811942 100644
--- a/backend/app/plugins_sdk/__init__.py
+++ b/backend/app/plugins_sdk/__init__.py
@@ -98,9 +98,13 @@ queue = QueueBusSdk()
notify = NotifySdk()
jobs = JobsSdk()
-# Imported lazily inside the accessor: deploys pulls in the deployment
-# services, which import models, and this module is imported very early.
-_deploys = None
+# Surfaces imported lazily inside __getattr__ — see its docstring. Each entry
+# is name -> (module path, attribute).
+_LAZY_SURFACES = {
+ 'deploys': ('app.plugins_sdk.deploys_sdk', 'deploys'),
+ 'search': ('app.plugins_sdk.search_sdk', 'search'),
+}
+_lazy_cache = {}
def panel_version():
@@ -139,6 +143,7 @@ __all__ = [
'notify',
'jobs',
'deploys',
+ 'search',
'permissions',
'require_permission',
'panel_version',
@@ -148,21 +153,23 @@ __all__ = [
def __getattr__(name):
- """Lazily expose ``deploys``.
+ """Lazily expose the surfaces that reach into host services.
- The deploy SDK imports the deployment services (and therefore models),
- while this module is imported early in app setup — binding it eagerly would
- make plugins_sdk import-order sensitive for everyone, including the plugins
- that never touch deployments.
+ These SDKs import services (and therefore models), while this module is
+ imported early in app setup — binding them eagerly would make plugins_sdk
+ import-order sensitive for everyone, including the plugins that never touch
+ deployments or search.
- The implementation lives in deploys_sdk.py, not deploys.py: a submodule of
- that name would be bound as a package attribute on import and shadow this
- accessor, handing callers the module instead of the SDK instance.
+ Each implementation lives in ``<name>_sdk.py``, not ``<name>.py``: a
+ submodule of the bare name would be bound as a package attribute on import
+ and shadow this accessor, handing callers the module instead of the SDK
+ instance.
"""
- if name == 'deploys':
- global _deploys
- if _deploys is None:
- from app.plugins_sdk.deploys_sdk import deploys as _d
- _deploys = _d
- return _deploys
- raise AttributeError(name)
+ target = _LAZY_SURFACES.get(name)
+ if target is None:
+ raise AttributeError(name)
+ if name not in _lazy_cache:
+ import importlib
+ module, attr = target
+ _lazy_cache[name] = getattr(importlib.import_module(module), attr)
+ return _lazy_cache[name]
diff --git a/backend/app/plugins_sdk/search_sdk.py b/backend/app/plugins_sdk/search_sdk.py
new file mode 100644
index 00000000..0507a226
--- /dev/null
+++ b/backend/app/plugins_sdk/search_sdk.py
@@ -0,0 +1,48 @@
+"""Plugin-facing SDK for global search.
+
+ from app.plugins_sdk import search
+
+ def find_worlds(query):
+ rows = World.query.filter(World.owner_id == query.user.id,
+ World.name.ilike(f'%{query.term}%'))
+ return [{'label': w.name, 'sublabel': 'Minecraft world',
+ 'path': f'/minecraft/worlds/{w.id}'} for w in rows]
+
+ search.register('minecraft.world', find_worlds)
+
+Registering makes a plugin's objects reachable from the command palette with no
+frontend work: an unrecognised type renders under "Results" with the generic
+icon rather than being dropped.
+
+Your provider is handed a ``search.Query`` — ``term``, ``user``, ``workspace_id``
+and ``limit`` — and **must scope its own rows to that user and workspace**. The
+panel applies no post-filter; every core block scopes itself, and search exists
+to surface what someone can already reach, never to widen it.
+"""
+
+from app.services import search_provider_registry
+from app.services.search_provider_registry import SearchQuery
+
+
+class SearchSdk:
+ """Stable search surface for plugins."""
+
+ #: The object a provider receives. Exposed so plugins can build one in
+ #: their own tests without importing a host service path.
+ Query = SearchQuery
+
+ def register(self, entity_type, provider, replace=False):
+ """Register ``provider(query) -> [{'label', 'path', 'sublabel'}, ...]``.
+
+ Namespace the type after your plugin (``minecraft.world``); bare names
+ are reserved for core entities. Rows are capped and normalised by the
+ host, and are always tagged with the type you registered.
+ """
+ return search_provider_registry.register(entity_type, provider, replace=replace)
+
+ def types(self):
+ """Entity types registered by plugins."""
+ return search_provider_registry.types()
+
+
+search = SearchSdk()
diff --git a/backend/app/services/search_provider_registry.py b/backend/app/services/search_provider_registry.py
new file mode 100644
index 00000000..ffa8d9cc
--- /dev/null
+++ b/backend/app/services/search_provider_registry.py
@@ -0,0 +1,126 @@
+"""Registry of searchable entity types contributed outside the core.
+
+``SearchService.search`` fans a term out across a hardcoded sequence of core
+entity blocks — fine while everything searchable lived in core, but it meant an
+extension's objects were absent from the one place users are told to look. A
+registered provider is fanned out alongside the core types, and the command
+palette already renders unknown types (they bucket under "Results" with the
+generic icon), so contributing rows takes no frontend work.
+
+A provider is ``fn(query) -> [row, ...]`` where *query* is a :class:`SearchQuery`
+and each row is ``{'label', 'path'}`` plus an optional ``'sublabel'``. The
+service normalises what comes back through :func:`clean_rows`, which is also the
+security seam: a provider cannot exceed the per-type cap, cannot claim to be a
+core type, and cannot return a path that navigates off-site.
+
+**Scoping is the provider's job.** Core applies no post-filter — every core
+block scopes its own query (``WorkspaceService.scope_query``, an owner column,
+an admin gate) and a provider must do the same with the ``user`` and
+``workspace_id`` on the query it is handed. Search invents no ACL; it must not
+become the place one leaks.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# entity type -> provider(query) -> rows
+_PROVIDERS = {}
+
+# The core entity types, reserved so a plugin cannot impersonate one — rows
+# tagged 'service' or 'vault' are trusted to have been scoped by core.
+CORE_TYPES = ('service', 'server', 'domain', 'database', 'site', 'cron',
+ 'extension', 'vault')
+
+
+@dataclass(frozen=True)
+class SearchQuery:
+ """What a provider is asked for, and who is asking.
+
+ Passed as one object rather than keyword arguments so later additions
+ (result kinds, an explicit tier) don't break every installed provider's
+ signature.
+ """
+
+ term: str
+ user: Any = None
+ workspace_id: Optional[int] = None
+ limit: int = 5
+
+
+def register(entity_type: str, provider, replace: bool = False):
+ """Register *provider* for *entity_type*.
+
+ Namespace the type after your plugin (``wordpress.site``); the bare words
+ in ``CORE_TYPES`` belong to core.
+ """
+ if not entity_type or not callable(provider):
+ raise ValueError('search provider requires an entity type and a callable')
+ if entity_type in CORE_TYPES:
+ raise ValueError(f'"{entity_type}" is a core search type and cannot be overridden')
+ if entity_type in _PROVIDERS and not replace:
+ raise ValueError(f'search provider for "{entity_type}" is already registered')
+ _PROVIDERS[entity_type] = provider
+ logger.info('Registered search provider: %s', entity_type)
+ return provider
+
+
+def get(entity_type: str):
+ """Return the provider for *entity_type*, or None."""
+ return _PROVIDERS.get(entity_type)
+
+
+def types():
+ """All registered non-core entity types."""
+ return sorted(_PROVIDERS)
+
+
+def providers():
+ """``(entity_type, provider)`` pairs, in a stable order."""
+ return [(t, _PROVIDERS[t]) for t in sorted(_PROVIDERS)]
+
+
+def clean_rows(entity_type: str, rows, limit: int):
+ """Normalise a provider's rows into the shape the palette renders.
+
+ Enforced here rather than trusted from the provider:
+
+ * the per-type cap, so one contributed type can't drown the core ones even
+ if it ignored ``query.limit``;
+ * ``type``, which is always the registered one — a plugin cannot dress its
+ rows up as a core entity;
+ * ``path``, which must be an in-app router path. It is handed to
+ ``navigate()`` unmodified, so a protocol-relative ``//host`` value would
+ send the user off the panel entirely.
+
+ Malformed rows are dropped individually — a provider with one bad row still
+ contributes its good ones.
+ """
+ cleaned = []
+ for row in (rows or []):
+ if len(cleaned) >= limit:
+ break
+ if not isinstance(row, dict):
+ continue
+ label = str(row.get('label') or '').strip()
+ path = str(row.get('path') or '').strip()
+ if not label or not path:
+ continue
+ if not path.startswith('/') or path.startswith('//'):
+ logger.warning('search: %s dropped a row with off-site path %r',
+ entity_type, path)
+ continue
+ cleaned.append({
+ 'type': entity_type,
+ 'label': label,
+ 'sublabel': str(row.get('sublabel') or ''),
+ 'path': path,
+ })
+ return cleaned
+
+
+def clear():
+ """Drop every registration. Tests only."""
+ _PROVIDERS.clear()
diff --git a/backend/app/services/search_service.py b/backend/app/services/search_service.py
index 6c54e15f..02f2e693 100644
--- a/backend/app/services/search_service.py
+++ b/backend/app/services/search_service.py
@@ -231,4 +231,23 @@ class SearchService:
except Exception:
logger.exception('search: vault fan-out failed')
+ # --- entities contributed by extensions (see search_provider_registry) ---
+ # Same isolation and cap as a core block: one broken provider degrades
+ # to "no rows of that type", and the cap is re-applied on this side
+ # rather than trusted from the provider.
+ try:
+ from app.services import search_provider_registry
+ contributed = search_provider_registry.providers()
+ except Exception:
+ logger.exception('search: provider registry unavailable')
+ contributed = []
+ for entity_type, provider in contributed:
+ try:
+ query = search_provider_registry.SearchQuery(
+ term=term, user=user, workspace_id=ws_id, limit=PER_TYPE_CAP)
+ rows.extend(search_provider_registry.clean_rows(
+ entity_type, provider(query), PER_TYPE_CAP))
+ except Exception:
+ logger.exception('search: %s fan-out failed', entity_type)
+
return rows
diff --git a/backend/tests/test_plugin_search_sdk.py b/backend/tests/test_plugin_search_sdk.py
new file mode 100644
index 00000000..1a12ee21
--- /dev/null
+++ b/backend/tests/test_plugin_search_sdk.py
@@ -0,0 +1,179 @@
+"""Searchable entities contributed by plugins (plugins_sdk.search).
+
+A plugin's objects were unreachable from the command palette — the one place
+users are told to look — because the fan-out was a hardcoded list of core
+types. Registering a provider puts them in it, and the palette renders unknown
+types already, so it takes no frontend change.
+
+The provider is trusted to scope its own rows (core applies no post-filter), but
+NOT trusted with the shape: the cap, the type tag and the path are enforced on
+the host side, which is what most of this file pins down.
+"""
+
+import pytest
+from flask_jwt_extended import create_access_token
+
+from app import db
+from app.models.application import Application
+from app.services import search_provider_registry
+from app.services.search_service import SearchService
+
+
[email protected](autouse=True)
+def _clean_registry():
+ search_provider_registry.clear()
+ yield
+ search_provider_registry.clear()
+
+
+def owner(app):
+ """A developer with one application, and their auth headers."""
+ from app.models import User
+ from werkzeug.security import generate_password_hash
+
+ with app.app_context():
+ user = User(email='[email protected]', username='srch_sdk',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_DEVELOPER, is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ db.session.add(Application(name='FindableApp', app_type='php',
+ user_id=user.id, root_path='/srv/findable'))
+ db.session.commit()
+ return {'id': user.id,
+ 'headers': {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}}
+
+
+def _row(label='World one', path='/minecraft/worlds/1', **extra):
+ return {'label': label, 'path': path, **extra}
+
+
+class TestRegistry:
+ def test_registers_and_resolves(self):
+ provider = lambda query: []
+ search_provider_registry.register('demo.thing', provider)
+ assert search_provider_registry.get('demo.thing') is provider
+ assert 'demo.thing' in search_provider_registry.types()
+
+ def test_core_types_cannot_be_hijacked(self):
+ # Rows tagged 'service' or 'vault' are trusted to have been scoped by
+ # core, so a plugin must not be able to mint them.
+ for entity_type in search_provider_registry.CORE_TYPES:
+ with pytest.raises(ValueError):
+ search_provider_registry.register(entity_type, lambda query: [])
+
+ def test_duplicate_registration_needs_replace(self):
+ search_provider_registry.register('demo.thing', lambda query: [])
+ with pytest.raises(ValueError):
+ search_provider_registry.register('demo.thing', lambda query: [])
+ search_provider_registry.register('demo.thing', lambda query: [], replace=True)
+
+ def test_rejects_non_callable(self):
+ with pytest.raises(ValueError):
+ search_provider_registry.register('demo.thing', 'not-callable')
+
+
+class TestRowCleaning:
+ def test_tags_rows_with_the_registered_type(self):
+ rows = search_provider_registry.clean_rows(
+ 'demo.thing', [_row(type='service')], 5)
+ # A provider claiming to be a core type is overruled, not obeyed.
+ assert rows[0]['type'] == 'demo.thing'
+
+ def test_fills_in_a_missing_sublabel(self):
+ assert search_provider_registry.clean_rows('demo.thing', [_row()], 5)[0]['sublabel'] == ''
+
+ def test_drops_rows_without_a_label_or_path(self):
+ bad = [{'path': '/x'}, {'label': 'no path'}, {'label': ' ', 'path': '/x'}]
+ assert search_provider_registry.clean_rows('demo.thing', bad, 5) == []
+
+ def test_drops_off_site_paths(self):
+ # The palette hands `path` straight to navigate(); a protocol-relative
+ # value would walk the user off the panel.
+ bad = [_row(path='//evil.example'), _row(path='https://evil.example'),
+ _row(path='relative')]
+ assert search_provider_registry.clean_rows('demo.thing', bad, 5) == []
+
+ def test_enforces_the_cap_even_when_the_provider_ignores_it(self):
+ many = [_row(label=f'World {i}', path=f'/w/{i}') for i in range(50)]
+ assert len(search_provider_registry.clean_rows('demo.thing', many, 5)) == 5
+
+ def test_survives_junk(self):
+ assert search_provider_registry.clean_rows('demo.thing', None, 5) == []
+ assert search_provider_registry.clean_rows('demo.thing', ['nope', 7], 5) == []
+
+
+class TestFanOut:
+ def test_contributed_rows_reach_the_endpoint(self, app, client, owner):
+ search_provider_registry.register(
+ 'minecraft.world',
+ lambda query: [_row(label='Overworld', sublabel='Minecraft world',
+ path='/minecraft/worlds/1')])
+
+ res = client.get('/api/v1/search?q=over', headers=owner['headers'])
+
+ assert res.status_code == 200
+ rows = res.get_json()['results']
+ contributed = [r for r in rows if r['type'] == 'minecraft.world']
+ assert contributed == [{'type': 'minecraft.world', 'label': 'Overworld',
+ 'sublabel': 'Minecraft world',
+ 'path': '/minecraft/worlds/1'}]
+
+ def test_a_broken_provider_does_not_break_search(self, app, client, owner):
+ def explode(query):
+ raise RuntimeError('provider is broken')
+
+ search_provider_registry.register('demo.broken', explode)
+
+ res = client.get('/api/v1/search?q=findable', headers=owner['headers'])
+
+ # The core rows still arrive — a bad provider degrades to no rows of
+ # its type rather than 500-ing the palette.
+ assert res.status_code == 200
+ assert any(r['type'] == 'service' for r in res.get_json()['results'])
+
+ def test_provider_is_told_who_is_asking(self, app, owner):
+ seen = {}
+
+ def capture(query):
+ seen['term'] = query.term
+ seen['user_id'] = query.user.id
+ seen['limit'] = query.limit
+ seen['workspace_id'] = query.workspace_id
+ return []
+
+ search_provider_registry.register('demo.capture', capture)
+
+ with app.app_context():
+ from app.models import User
+ SearchService.search(User.query.get(owner['id']), 'findable')
+
+ # Without the user the provider cannot scope its rows, which is the
+ # contract it is required to honour.
+ assert seen['term'] == 'findable'
+ assert seen['user_id'] == owner['id']
+ assert seen['limit'] == 5
+ assert seen['workspace_id'] is None
+
+ def test_short_terms_never_reach_providers(self, app, client, owner):
+ called = []
+ search_provider_registry.register('demo.thing',
+ lambda query: called.append(1) or [])
+
+ assert client.get('/api/v1/search?q=a', headers=owner['headers']).status_code == 200
+ assert called == []
+
+
+class TestSdkFacade:
+ def test_sdk_registers_and_lists(self, app):
+ from app import plugins_sdk
+
+ plugins_sdk.search.register('demo.sdk', lambda query: [])
+ assert 'demo.sdk' in plugins_sdk.search.types()
+
+ def test_sdk_exposes_the_query_type(self):
+ from app import plugins_sdk
+
+ query = plugins_sdk.search.Query(term='abc', limit=3)
+ assert (query.term, query.limit, query.user) == ('abc', 3, None)