"""插件元数据。

定义插件清单相关的枚举、不可变值对象，包括失败策略、插件依赖、资源配额、
配置字段、渠道清单与插件清单。所有 DTO 均为 ``dataclass(frozen=True)``，
集合字段使用 tuple，仅依赖标准库与契约层内部类型，用于插件注册、依赖解析、
资源配额声明与能力边界声明。
"""

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime
from enum import StrEnum
from typing import Any

from yuxi.channels.contract.dtos.capability import ChannelCapabilities
from yuxi.channels.contract.dtos.channel import ChannelType
from yuxi.channels.contract.dtos.config import ConfigField
from yuxi.channels.contract.dtos.plugin import EnvVar


class FailurePolicy(StrEnum):
    """失败策略。

    标识插件失败时的处理策略，用于宿主决定降级、熔断或隔离。继承
    ``str, Enum`` 以支持 JSON 序列化与字符串比较。

    取值：
        DEGRADE: 降级（走降级路径，保留部分能力）。
        CIRCUIT_BREAK: 熔断（打开熔断器，暂时停止调用）。
        ISOLATE: 隔离（隔离插件，阻止其继续运行）。
    """

    DEGRADE = "degrade"
    CIRCUIT_BREAK = "circuit_break"
    ISOLATE = "isolate"


@dataclass(frozen=True)
class PluginDependency:
    """插件依赖。

    描述插件对其他插件的依赖关系，包括插件 ID 与版本范围，用于插件加载
    前的依赖解析。

    字段：
        plugin_id: 依赖的插件 ID。
        version_range: 语义化版本范围表达式（SemVer range）。
    """

    plugin_id: str
    version_range: str


@dataclass(frozen=True)
class ResourceQuota:
    """资源配额。

    描述插件的资源配额限制，包括 CPU、内存、连接数与每秒调用数，用于
    宿主对插件施加资源边界（FR-32 / §8.5）。

    字段：
        max_cpu: CPU 上限（如 "500m"），可选。
        max_memory: 内存上限（如 "512Mi"），可选。
        max_connections: 最大连接数，可选。
        max_calls_per_sec: 每秒最大调用数，可选。
    """

    max_cpu: str | None = None
    max_memory: str | None = None
    max_connections: int | None = None
    max_calls_per_sec: int | None = None


@dataclass(frozen=True)
class ChannelManifest:
    """渠道清单。

    描述渠道插件的元数据，包括标识、版本、渠道类型、提供的能力、配置 schema、
    入口模块、依赖、生命周期、兼容性、失败策略、资源配额与能力边界声明，
    用于插件注册与装配。

    字段：
        id: 全局唯一标识（如 com.yuxi.channels.feishu）。
        name: 人类可读名称。
        version: 语义化版本。
        channel_type: 渠道类型。
        provides: 提供的能力列表。
        entry_module: 插件入口模块路径。
        capabilities: 渠道能力集合（静态声明，必填）。
        config_schema: 配置项 schema（必填）。
        depends: 依赖的其他插件（默认空）。
        lifecycle: 支持的生命周期钩子（默认 init/start/stop/unload）。
        compatibility: 兼容性信息（可选）。
        failure_policy: 失败策略（默认 DEGRADE）。
        resource_quota: 资源配额（可选）。
        accessible_ports: 可访问的端口列表（默认空）。
        injectable_pipelines: 可注入的管道列表（默认空）。
        skills: 提供的技能列表（默认空）。
        env_vars: 环境变量声明（默认空）。
        critical: 是否为关键渠道（默认 False）。关键渠道失败时宿主标记为
            ``unhealthy``，非关键渠道失败标记为 ``degraded``（FR-31 / FR-35）。
        requires_dm_pairing: 是否要求 DM 安全配对审批（默认 True）。声明
            ``False`` 的渠道（如已通过宿主认证体系）跳过 DM 配对审批直接放行
            （FR-31）。插件未注册时框架回退为 ``True``（fail-closed）。
        requires_outbound_delivery: 是否要求出站投递（默认 True）。声明 ``False``
            的渠道无需实现 ``OutboundAdapter``，框架跳过出站投递阶段（FR-31）。
    """

    id: str
    name: str
    version: str
    channel_type: ChannelType
    provides: tuple[str, ...]
    entry_module: str
    capabilities: ChannelCapabilities
    config_schema: tuple[ConfigField, ...]
    depends: tuple[PluginDependency, ...] = ()
    lifecycle: tuple[str, ...] = ("init", "start", "stop", "unload")
    compatibility: dict[str, Any] | None = None
    failure_policy: FailurePolicy = FailurePolicy.DEGRADE
    resource_quota: ResourceQuota | None = None
    accessible_ports: tuple[str, ...] = ()
    injectable_pipelines: tuple[str, ...] = ()
    skills: tuple[str, ...] = ()
    env_vars: tuple[EnvVar, ...] = ()
    critical: bool = False
    requires_dm_pairing: bool = True
    requires_outbound_delivery: bool = True


@dataclass(frozen=True)
class PluginManifest:
    """插件清单。

    描述插件注册到宿主的完整清单，包括渠道清单与插件提供的扩展点（适配器、
    阶段、事件订阅、配置源），由 ``CHANNEL_ENTRY`` 返回给宿主。

    字段：
        manifest: 渠道清单。
        adapters: 提供的适配器类型列表（默认空）。
        stages: 提供的管道阶段列表（默认空）。
        event_subscriptions: 订阅的事件类型列表（默认空）。
        config_sources: 配置源列表（默认空）。
        installed_at: 文件级安装时间（PLG-INSTALL 端点写入，默认 None
            表示未通过文件级安装流程注册）。
        install_source: 安装来源标识（如文件路径、URL、包名，默认 None）。
        install_version: 安装时的版本号（可能与 manifest.version 不同，
            如安装后未升级，默认 None）。
    """

    manifest: ChannelManifest
    adapters: tuple[str, ...] = ()
    stages: tuple[str, ...] = ()
    event_subscriptions: tuple[str, ...] = ()
    config_sources: tuple[str, ...] = ()
    installed_at: datetime | None = None
    install_source: str | None = None
    install_version: str | None = None