shopdb-flask/shopdb/core/api/plugins.py

"""Plugin introspection + enable/disable API."""

from flask import Blueprint, current_app, request
from flask_jwt_extended import jwt_required

from shopdb.plugins.base import renderable_settings_routes
from shopdb.utils.responses import success_response, error_response, ErrorCodes

from shopdb.utils.authz import require_role
from shopdb.utils.authz import require_permission

plugins_bp = Blueprint('plugins', __name__)


@plugins_bp.route('', methods=['GET'])
@require_permission('settings.view')
def list_plugins():
    """List all discovered plugins (enabled or not) with their metadata and
    the framework contract version."""
    from shopdb import __contract_version__
    pm = current_app.extensions.get('plugin_manager')
    plugins = pm.discover_available() if pm else []
    plugins.sort(key=lambda p: p['name'])
    return success_response({
        'contract_version': __contract_version__,
        'count': len(plugins),
        'plugins': plugins,
    })


@plugins_bp.route('/enabled', methods=['GET'])
@jwt_required(optional=True)
def list_enabled_plugins():
    """Return just the names of enabled plugins as a flat array.

    Cheap registry read (no DB). Exposed to anonymous callers on purpose:
    the navigation endpoint already leaks the same enabled/disabled signal,
    and the frontend needs it (including unauthenticated kiosk routes like
    /tv) to gate plugin-owned routes. No metadata beyond the names.
    """
    pm = current_app.extensions.get('plugin_manager')
    names = pm.registry.get_enabled_plugins() if pm else []
    return success_response(sorted(names))


@plugins_bp.route('/settings-routes', methods=['GET'])
@require_permission('settings.view')
def get_plugin_settings_routes():
    """Return settings routes contributed by all enabled plugins.

    Plugins can register routes to add tabs/pages to settings hubs like
    Model Catalog, Asset Config, etc. Frontend router merges these dynamically.

    Gated on settings.view, the same permission list_plugins carries. It was
    optional-auth and listed as a public read, on the stated reasoning that
    unauthenticated pages (kiosks, TV displays) register plugin tabs before
    login. Nothing does: the only caller in the frontend is
    views/settings/ModelCatalogHub.vue, which sits behind requiresAuth and
    requiresAdmin, and no kiosk route touches it. Open, it handed an anonymous
    caller the enabled plugin list, the settings hub layout and the internal Vue
    component paths - free reconnaissance about which modules a site runs. The
    login page never calls this, so gating it costs nothing pre-login.

    A route naming a hub that has no code to draw plugin tabs is DROPPED here,
    loudly. Returning it would put an entry in a response that nothing reads:
    the plugin author sees a correct declaration and an API that accepts it, and
    the tab never appears anywhere. Dropping it costs the same missing tab and
    leaves a line in the log that says which plugin, which hub, and what the
    supported set is. See SETTINGS_HUBS_WITH_PLUGIN_TABS in shopdb/plugins/base.

    Returns: { routes: [{hub, path, name, tab, component}, ...] }
    """
    pm = current_app.extensions.get('plugin_manager')
    if not pm:
        return success_response({'routes': []})

    routes = []
    for plugin_name, plugin in pm.get_all_plugins().items():
        # Only include routes from enabled plugins
        if not pm.registry.is_enabled(plugin_name):
            continue
        if not hasattr(plugin, 'get_settings_routes'):
            continue
        # One broken plugin must not take every settings hub down with it.
        try:
            plugin_routes = plugin.get_settings_routes()
        except Exception:
            current_app.logger.exception(
                'get_settings_routes failed for plugin %s; skipping it',
                plugin_name)
            continue
        routes.extend(renderable_settings_routes(plugin_name, plugin_routes,
                                                 current_app.logger))

    return success_response({'routes': routes})


@plugins_bp.route('/<name>', methods=['PUT'])
@jwt_required()
@require_role('admin')
def set_plugin_enabled(name: str):
    """Enable or disable a plugin. Takes effect on the next app restart for
    route/navigation changes."""
    data = request.get_json() or {}
    if 'enabled' not in data:
        return error_response(ErrorCodes.VALIDATION_ERROR, 'enabled is required')

    pm = current_app.extensions.get('plugin_manager')
    if not pm:
        return error_response(ErrorCodes.INTERNAL_ERROR,
                              'Plugin manager unavailable', http_code=500)

    want = bool(data['enabled'])
    ok = pm.enable_plugin(name) if want else pm.disable_plugin(name)
    if not ok:
        # enable/disable refused (unknown plugin, or a dependency conflict)
        return error_response(
            ErrorCodes.CONFLICT,
            f"Could not {'enable' if want else 'disable'} '{name}' "
            f"(check it exists and dependencies allow it)",
            http_code=409
        )

    return success_response(
        {'name': name, 'enabled': want},
        # No longer "restart to apply": each worker notices the change to
        # plugins.json and recycles itself, so the routes follow on their own
        # within seconds. Callers poll /setup/health to know when that has
        # finished across the pool.
        message=f"Plugin {'enabled' if want else 'disabled'}. "
                f"It comes online as the workers pick up the change."
    )