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): 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__.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 rowsdiff --git a/backend/tests/test_plugin_search_sdk.py b/backend/tests/test_plugin_search_sdk.pynew file mode 100644index 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)