RuoYi-Vue3-FastAPI/ruoyi-fastapi-backend/plugins/core/runtime/explicit.py

import inspect
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Any

from fastapi import Depends, FastAPI, HTTPException
from starlette.requests import Request
from starlette.routing import Mount
from starlette.types import Scope

from config.database import Base, DataSourceRegistry
from exceptions.exception import AuthException
from module_admin.service.login_service import LoginService
from plugins.core.discovery.registry import PluginRegistry, RegisteredPlugin
from plugins.core.discovery.scanner import is_artifact_plugin
from plugins.core.runtime.asgi import PluginGatewayASGI, PluginLifespanManager
from plugins.core.runtime.browser_session import authenticate_browser_session
from plugins.core.runtime.bundle import PluginBundleASGI
from plugins.core.runtime.configuration import PluginConfigObservation, PluginConfigReader, config_revision
from plugins.core.runtime.connections import AUTH_RECHECK_KEY
from plugins.core.runtime.diagnostics import (
    PluginActivationHealth,
    PluginRuntimeDiagnosticSnapshot,
    activation_health_observation,
    collect_runtime_diagnostics,
)
from plugins.core.runtime.entrypoint import PluginEntrypointLoader
from plugins.core.runtime.health import PluginHealthChecker
from plugins.core.runtime.host_services import build_host_services
from plugins.core.runtime.job_dispatcher import PluginJobBinding, bind_plugin_jobs, unbind_plugin_jobs
from plugins.core.runtime.metrics import PluginObservedASGI, PluginRuntimeMetrics
from plugins.core.runtime.metrics_store import PluginMetricsReporter
from plugins.core.runtime.route_guard import PluginEnabledDependency, PluginRouteStateGateway
from plugins.core.sdk import PluginDefinition, PluginHostContext, PluginRequestContext
from plugins.core.sdk.request import current_plugin_request_id
from plugins.core.validation.manifest import PluginManifestChecker
from plugins.core.validation.structure import PluginStructureChecker
from utils.log_util import logger


@dataclass
class LoadedExplicitPlugin:
    """
    一个 worker 的已加载定义及可选 lifespan。

    :param plugin: 注册表中的插件记录
    :param host: 当前插件的宿主能力上下文
    :param definition: 入口返回的插件能力定义
    :param lifespan: ASGI 子应用生命周期管理器
    :param active: 插件是否已完成激活
    :param jobs: 当前 worker 中的插件任务绑定
    :param gateway: 当前 worker 的 ASGI 长连接管理入口
    :param activation_health: 最近一次激活健康检查的安全摘要，不表示持续健康
    """

    plugin: RegisteredPlugin
    host: PluginHostContext
    definition: PluginDefinition
    lifespan: PluginLifespanManager | None = None
    active: bool = False
    jobs: PluginJobBinding | None = None
    gateway: PluginGatewayASGI | None = None
    activation_health: PluginActivationHealth = field(default_factory=PluginActivationHealth)


class ExplicitPluginRuntime:
    """
    仅负责当前 worker 的代码和资源，全局迁移仍由原有 writer 处理。
    """

    def __init__(self, route_state_gateway: PluginRouteStateGateway) -> None:
        """
        初始化当前 worker 的显式插件运行时。

        :param route_state_gateway: 插件启用状态查询网关
        :return: None
        """
        self.route_state_gateway = route_state_gateway
        self.loaded: dict[str, LoadedExplicitPlugin] = {}
        self.metrics = PluginRuntimeMetrics()
        self.metrics_reporter = PluginMetricsReporter(self.metrics)
        self._closing = False

    def diagnostic_snapshot(self) -> PluginRuntimeDiagnosticSnapshot:
        """
        读取当前 worker 已加载插件的身份、资源与最近激活检查，不触发插件回调。

        :return: 与旧版 metrics 协议独立的有界诊断快照
        """
        return collect_runtime_diagnostics(self)

    @staticmethod
    def ordered_plugins(registry: PluginRegistry) -> list[RegisteredPlugin]:
        """
        稳定的依赖拓扑排序，拒绝缺失依赖及循环。

        :param registry: 包含待排序插件的注册表
        :return: 按依赖优先顺序排列的已启用插件
        """
        plugins = {item.plugin_id: item for item in registry.list_enabled_plugins()}
        visiting: set[str] = set()
        visited: set[str] = set()
        result = []

        def visit(plugin_id: str) -> None:
            """
            递归访问插件依赖并记录拓扑顺序。

            :param plugin_id: 当前访问的插件 ID
            :return: None
            """
            if plugin_id in visited:
                return
            if plugin_id in visiting:
                raise ValueError(f'插件存在循环依赖：{plugin_id}')
            if plugin_id not in plugins:
                raise ValueError(f'插件依赖未启用：{plugin_id}')
            visiting.add(plugin_id)
            plugin = plugins[plugin_id]
            for dependency in plugin.discovered_plugin.manifest.dependencies.plugins:
                visit(dependency.id)
            visiting.remove(plugin_id)
            visited.add(plugin_id)
            result.append(plugin)

        for plugin_id in plugins:
            visit(plugin_id)
        return result

    @classmethod
    def dependency_order(cls, registry: PluginRegistry) -> tuple[list[RegisteredPlugin], dict[str, str]]:
        """
        按依赖闭包分别排序，损坏分支不阻断独立插件。

        :param registry: 包含全部已发现插件的注册表
        :return: 可加载的插件依赖顺序及各失败入口的错误信息
        """
        plugins = {item.plugin_id: item for item in registry.list_enabled_plugins()}
        ordered: dict[str, RegisteredPlugin] = {}
        errors: dict[str, str] = {}
        for plugin_id, plugin in plugins.items():
            if not plugin.discovered_plugin.manifest.uses_entrypoint:
                continue
            closure: dict[str, RegisteredPlugin] = {}

            def collect(current: str, closure: dict[str, RegisteredPlugin] = closure) -> None:
                """
                收集当前入口依赖的插件闭包。

                :param current: 当前访问的插件 ID
                :param closure: 当前入口已收集的依赖插件映射
                :return: None
                """
                if current in closure:
                    return
                if current not in plugins:
                    raise ValueError(f'插件依赖未启用：{current}')
                closure[current] = plugins[current]
                for dependency in plugins[current].discovered_plugin.manifest.dependencies.plugins:
                    collect(dependency.id, closure)

            try:
                collect(plugin_id)
                for dependency in cls.ordered_plugins(PluginRegistry(list(closure.values()))):
                    ordered[dependency.plugin_id] = dependency
            except ValueError as exc:
                errors[plugin_id] = str(exc)
        return list(ordered.values()), errors

    def prepare(
        self,
        plugin: RegisteredPlugin,
        app: FastAPI,
        *,
        startup_write_enabled: bool,
        config_values: Mapping[str, Any] | None = None,
    ) -> None:
        """
        导入显式模型定义，在原有建表步骤之前完成。

        :param plugin: 注册表中的待准备插件
        :param app: 宿主 FastAPI 应用
        :param startup_write_enabled: 当前 worker 是否允许执行启动期全局写入
        :param config_values: 插件专属配置快照，未提供时使用清单默认值
        :return: None
        """
        if plugin.plugin_id in self.loaded:
            return
        discovered = plugin.discovered_plugin
        manifest = discovered.manifest
        builder = getattr(app.state, 'plugin_runtime_builder', None)
        backend_root = getattr(builder, 'backend_root', discovered.backend_path.parents[1])
        structure = PluginStructureChecker(backend_root).check(discovered, include_frontend=False)
        if not structure.ok:
            raise ValueError('；'.join(item.message for item in structure.failed_items))
        compatibility = PluginManifestChecker(backend_root=backend_root).check(manifest)
        if not compatibility.ok:
            raise ValueError('；'.join(item.message for item in compatibility.error_issues))
        values = (
            dict(config_values)
            if config_values is not None
            else {item.key: item.default for item in manifest.config.items}
        )
        observation = PluginConfigObservation(
            plugin_id=plugin.plugin_id,
            version=manifest.version,
            digest=discovered.artifact_digest,
            generation=discovered.artifact_generation,
            startup_revision=config_revision(plugin.plugin_id, values),
        )
        host = PluginHostContext(
            plugin_id=plugin.plugin_id,
            resource_root=discovered.backend_path,
            config=values,
            config_revision=observation.startup_revision,
            config_reader=PluginConfigReader(discovered, DataSourceRegistry.session, observation).read,
            session_factory=DataSourceRegistry.session,
            services=build_host_services(
                plugin.plugin_id, DataSourceRegistry.session, getattr(app.state, 'redis', None)
            ),
            redis=getattr(app.state, 'redis', None),
            logger=logger.bind(plugin_id=plugin.plugin_id),
            startup_write_enabled=startup_write_enabled and not is_artifact_plugin(discovered),
        )
        existing_tables = set(Base.metadata.tables)
        try:
            definition = PluginEntrypointLoader(discovered).load(host)
            if definition.register_models:
                result = definition.register_models(host)
                if inspect.isawaitable(result):
                    if inspect.iscoroutine(result):
                        result.close()
                    raise TypeError('register_models 必须同步注册元数据，不能执行异步数据库操作')
        finally:
            if is_artifact_plugin(discovered):
                for key in set(Base.metadata.tables) - existing_tables:
                    Base.metadata.tables[key].info['plugin_artifact'] = plugin.plugin_id
        self.loaded[plugin.plugin_id] = LoadedExplicitPlugin(plugin, host, definition)
        worker = getattr(app.state, 'plugin_release_worker', None)
        if worker is not None:
            self.metrics.worker_id = worker.worker_id
        self.metrics.register(
            plugin.plugin_id, manifest.version, discovered.artifact_digest, discovered.artifact_generation
        )
        if plugin.plugin_id in self.metrics.identities:
            self.metrics.configurations[plugin.plugin_id] = observation
        app.state.plugin_metrics_reporter = self.metrics_reporter

    async def activate(self, plugin_id: str, app: FastAPI) -> None:
        """
        全部校验和初始化成功后才向应用注册路由或挂载子应用。

        :param plugin_id: 已完成准备的插件 ID
        :param app: 宿主 FastAPI 应用
        :return: None
        """
        if self._closing:
            raise RuntimeError('插件运行时已进入关闭阶段，不能激活插件')
        loaded = self.loaded[plugin_id]
        if loaded.active:
            return
        if loaded.lifespan is not None and loaded.lifespan.has_pending_task:
            raise RuntimeError(f'插件上一次生命周期尚未退出：{plugin_id}')
        if loaded.plugin.discovered_plugin.manifest.backend.jobs:
            loaded.jobs = bind_plugin_jobs(
                loaded.plugin.discovered_plugin,
                loaded.host,
                self.route_state_gateway,
                lambda: loaded.active and (loaded.lifespan is None or loaded.lifespan.ready),
                metrics=self.metrics,
            )
        try:
            await self._activate_web(loaded, app)
        except BaseException:
            if loaded.jobs is not None:
                try:
                    await unbind_plugin_jobs(loaded.jobs)
                    if not any(not task.done() for task in loaded.jobs.tasks):
                        loaded.jobs = None
                except Exception:
                    logger.exception(f'插件激活失败后的任务回收失败：{plugin_id}')
            raise
        loaded.active = True
        if plugin_id in self.metrics.configurations:
            self.metrics.configurations[plugin_id].active = True
        app.openapi_schema = None

    async def _activate_web(self, loaded: LoadedExplicitPlugin, app: FastAPI) -> None:
        """
        任务绑定成功后再注册 Web 能力，避免重复 worker 实例留下半注册路由。

        :param loaded: 当前 worker 已准备的插件实例
        :param app: 宿主 FastAPI 应用
        :return: None
        """
        plugin_id = loaded.plugin.plugin_id
        manifest = loaded.plugin.discovered_plugin.manifest
        if manifest.integration_kind == 'router':
            await self._check_health(loaded, app)
            if self._closing:
                raise RuntimeError('插件运行时已进入关闭阶段，不能注册路由')
            self._register_routers(loaded, app)
        else:
            child = loaded.definition.app_factory(loaded.host)
            if inspect.isawaitable(child):
                if inspect.iscoroutine(child):
                    child.close()
                raise TypeError('app_factory 必须同步返回 ASGI 应用')
            if not callable(child):
                raise TypeError('app_factory 必须返回 ASGI callable')
            if isinstance(child, FastAPI):
                child.state.plugin_host = loaded.host
                child.state.redis = loaded.host.redis
            mount_path = manifest.backend.asgi.mount_path
            if any(getattr(route, 'path', None) == mount_path for route in app.routes):
                raise ValueError(f'插件挂载路径冲突：{mount_path}')
            manager = PluginLifespanManager(child, managed=manifest.backend.asgi.lifespan == 'managed')
            loaded.lifespan = manager
            try:
                await manager.startup()
                await self._check_health(loaded, app)
                if self._closing:
                    raise RuntimeError('插件运行时已进入关闭阶段，不能挂载子应用')
                web_app = child
                if manifest.frontend.delivery.type == 'bundle':
                    web_app = PluginBundleASGI(child, plugin_id, loaded.plugin.backend_path, manifest.frontend.bundle)
                gateway = PluginGatewayASGI(web_app, manager, self._authorizer(loaded, app))
                observed = PluginObservedASGI(gateway, self.metrics, plugin_id)
                app.router.routes.append(Mount(mount_path, app=observed, name=f'plugin:{plugin_id}'))
                loaded.gateway = gateway
            except BaseException:
                try:
                    await manager.shutdown()
                except Exception:
                    logger.exception(f'插件激活失败后的 ASGI 回收失败：{plugin_id}')
                raise

    @staticmethod
    async def _check_health(loaded: LoadedExplicitPlugin, app: FastAPI) -> None:
        """
        执行清单声明的健康检查并阻止不健康插件激活。

        :param loaded: 当前 worker 已准备的插件实例
        :param app: 宿主 FastAPI 应用
        :return: None
        """
        if loaded.plugin.discovered_plugin.manifest.backend.health.checker:
            result = await PluginHealthChecker(loaded.plugin.discovered_plugin).check(app=app)
            loaded.activation_health = activation_health_observation(result)
            if not result.ok:
                raise RuntimeError(f'插件激活健康检查失败：{result.message}')

    def _register_routers(self, loaded: LoadedExplicitPlugin, app: FastAPI) -> None:
        """
        校验插件路由命名空间并注册带宿主权限依赖的路由。

        :param loaded: 当前 worker 已准备的插件实例
        :param app: 宿主 FastAPI 应用
        :return: None
        """
        plugin_id = loaded.plugin.plugin_id

        async def set_context(request: Request, user: Any = Depends(LoginService.get_current_user)) -> None:
            """
            检查插件状态并向请求写入宿主身份上下文。

            :param request: 插件接口请求
            :param user: 宿主登录依赖返回的当前用户
            :return: None
            """
            if not loaded.active:
                raise HTTPException(status_code=503, detail='插件未就绪')
            try:
                request.state.plugin_context = self._request_context(loaded, user)
            except PermissionError as exc:
                raise HTTPException(status_code=403, detail=str(exc)) from exc

        for router in loaded.definition.routers:
            for route in router.routes:
                if not PluginStructureChecker._is_plugin_route_prefix(plugin_id, getattr(route, 'path', '')):
                    raise ValueError(f'插件路由越过命名空间：{getattr(route, "path", "")}')
                if not hasattr(route, 'methods'):
                    raise ValueError('v2 Router 的 WebSocket 或嵌套 Mount 请使用 ASGI 接入')
        for router in loaded.definition.routers:
            previous_routes = len(app.router.routes)
            app.include_router(
                router,
                dependencies=[
                    PluginEnabledDependency(plugin_id, self.route_state_gateway),
                    Depends(set_context),
                ],
            )
            for route in app.router.routes[previous_routes:]:
                route.handle = PluginObservedASGI(route.handle, self.metrics, plugin_id)

    def _authorizer(self, loaded: LoadedExplicitPlugin, app: FastAPI) -> Any:
        """
        创建复用宿主登录及插件会话校验的 ASGI 授权器。

        :param loaded: 当前 worker 已准备的插件实例
        :param app: 宿主 FastAPI 应用
        :return: 根据请求作用域构建插件身份上下文的异步函数
        """

        async def authorize(scope: Scope) -> PluginRequestContext:
            # LoginService 使用宿主 request.app.state，而子应用会替换 scope['app']。
            """
            校验插件启用状态和登录凭证，并构建插件请求身份。

            :param scope: HTTP 或 WebSocket 的 ASGI 请求作用域
            :return: 已通过宿主身份及插件访问权限校验的请求上下文
            """
            auth_scope = dict(scope, type='http', app=app)
            request = Request(auth_scope)
            if not loaded.active:
                raise PermissionError('插件未激活或正在关闭')
            authorization = request.headers.get('authorization', '')
            scheme, _, token = authorization.partition(' ')
            async with DataSourceRegistry.session() as db:
                if not await self.route_state_gateway.is_plugin_enabled(db, loaded.plugin.plugin_id):
                    raise PermissionError('插件未启用')
                if authorization:
                    if scheme.lower() != 'bearer' or not token.strip():
                        raise LookupError('Bearer 凭证无效')
                    try:
                        resolve_user = (
                            LoginService.get_current_user_for_plugin_session
                            if scope.get(AUTH_RECHECK_KEY)
                            else LoginService.get_current_user
                        )
                        user = await resolve_user(request=request, token=token.strip(), query_db=db)
                    except AuthException as exc:
                        raise LookupError('登录已失效') from exc
                elif loaded.plugin.discovered_plugin.manifest.frontend.delivery.type == 'bundle':
                    user = await authenticate_browser_session(
                        request,
                        plugin_id=loaded.plugin.plugin_id,
                        version=loaded.plugin.discovered_plugin.manifest.version,
                        query_db=db,
                        websocket=scope['type'] == 'websocket',
                    )
                else:
                    raise LookupError('缺少 Bearer 凭证')
            return self._request_context(loaded, user)

        return authorize

    @staticmethod
    def _request_context(loaded: LoadedExplicitPlugin, user: Any) -> PluginRequestContext:
        """
        检查插件访问权限并构建宿主签发的请求上下文。

        :param loaded: 当前 worker 已准备的插件实例
        :param user: 宿主登录服务返回的当前用户
        :return: 绑定插件能力与当前用户身份的请求上下文
        """
        permissions = frozenset(user.permissions)
        declared = set(loaded.plugin.discovered_plugin.manifest.permission_codes)
        if declared and '*:*:*' not in permissions and not declared.intersection(permissions):
            raise PermissionError('缺少插件访问权限')
        return PluginRequestContext(loaded.host, user, permissions, request_id=current_plugin_request_id())

    async def shutdown(self) -> None:
        """
        逆序关闭，每个实例的失败不阻止其他实例释放资源。

        :return: None
        """
        self._closing = True
        instances = list(reversed(self.loaded.values()))
        for loaded in instances:
            loaded.active = False
            if loaded.plugin.plugin_id in self.metrics.configurations:
                self.metrics.configurations[loaded.plugin.plugin_id].active = False
        for loaded in instances:
            if loaded.gateway is not None:
                try:
                    await loaded.gateway.drain()
                except Exception:
                    logger.exception(f'插件长连接关闭失败：{loaded.plugin.plugin_id}')
            if loaded.jobs is not None:
                try:
                    await unbind_plugin_jobs(loaded.jobs)
                    if not any(not task.done() for task in loaded.jobs.tasks):
                        loaded.jobs = None
                except Exception:
                    logger.exception(f'插件任务关闭失败：{loaded.plugin.plugin_id}')
            if loaded.lifespan is not None:
                try:
                    await loaded.lifespan.shutdown()
                except Exception:
                    logger.exception(f'插件 ASGI 关闭失败：{loaded.plugin.plugin_id}')
        try:
            await self.metrics_reporter.stop()
        except Exception:
            logger.exception('插件指标上报关闭失败')