RuoYi-Vue3-FastAPI/ruoyi-fastapi-backend/cli/groups/plugin/commands/artifact.py

from collections.abc import Callable
from pathlib import Path
from typing import Annotated, Any

import typer

from cli.context import AllowProdOption, DryRunOption, EnvOption, OutputOption, YesOption
from cli.groups.plugin.commands.artifact_maintenance import register_artifact_maintenance_commands

MaintenanceOption = Annotated[
    bool, typer.Option('--maintenance', help='确认已停止全部宿主worker，并在独立维护进程执行')
]
ExpectedGenerationOption = Annotated[
    str, typer.Option('--expected-generation', help='最近一次plan/status返回的发布代际，防止并发覆盖')
]


def register_artifact_commands(app: typer.Typer, get_controller: Callable[[], Any]) -> None:
    """
    注册制品与维护发布命令，帮助和补全阶段不加载配置或数据库。

    :param app: Typer 命令组
    :param get_controller: 制品命令控制器工厂
    :return: None
    """
    artifact_app = typer.Typer(help='构建、验证和导入签名插件制品', no_args_is_help=True)
    release_app = typer.Typer(help='维护准备、目标选择和worker实际加载状态', no_args_is_help=True)
    app.add_typer(artifact_app, name='artifact')
    app.add_typer(release_app, name='release')
    register_artifact_maintenance_commands(artifact_app, get_controller)
    _register_release_enablement(release_app, get_controller)

    @artifact_app.command('build', help='离线签名打包预构建插件目录，不覆盖已有输出')
    def artifact_build(
        source: Annotated[Path, typer.Argument(help='已构建插件目录，目录名必须与插件ID一致')],
        destination: Annotated[Path, typer.Argument(help='输出.rpk文件')],
        key_file: Annotated[Path, typer.Option('--key-file', help='插件目录之外的Ed25519 PKCS8 PEM签名私钥')],
        key_id: Annotated[str, typer.Option('--key-id', help='发布者公钥标识')],
        password_env: Annotated[str | None, typer.Option('--password-env', help='读取加密私钥密码的环境变量名')] = None,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
    ) -> None:
        """
        离线签名打包预构建插件目录。

        :param source: 已构建插件目录
        :param destination: 签名制品输出文件
        :param key_file: 插件目录之外的 Ed25519 PKCS8 私钥文件
        :param key_id: 发布者公钥标识
        :param password_env: 保存加密私钥密码的环境变量名称
        :param env: 当前命令运行环境
        :param output: 输出格式
        :return: None
        """
        get_controller().build_artifact(
            source, destination, env, output, key_file=key_file, key_id=key_id, password_env=password_env
        )

    @artifact_app.command('verify', help='使用宿主信任公钥和发布者范围验证制品，不加载插件')
    def artifact_verify(
        path: Annotated[Path, typer.Argument(help='待验证.rpk文件')],
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
    ) -> None:
        """
        使用宿主信任配置验证制品。

        :param path: 待处理的签名制品文件
        :param env: 当前命令运行环境
        :param output: 输出格式
        :return: None
        """
        get_controller().verify_artifact(path, env, output)

    @artifact_app.command('import', help='验证并导入不可变存储和制品索引，不安装或激活')
    def artifact_import(
        path: Annotated[Path, typer.Argument(help='待导入.rpk文件')],
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
        allow_prod: AllowProdOption = False,
        yes: YesOption = False,
        dry_run: DryRunOption = False,
    ) -> None:
        """
        导入不可变制品及索引，暂不激活插件。

        :param path: 待处理的签名制品文件
        :param env: 当前命令运行环境
        :param output: 输出格式
        :param allow_prod: 是否允许生产环境危险命令
        :param yes: 是否跳过确认
        :param dry_run: 是否仅预演而不写入发布状态
        :return: None
        """
        get_controller().import_artifact(path, env, output, allow_prod=allow_prod, yes=yes, dry_run=dry_run)

    @artifact_app.command('list', help='查询已导入制品')
    def artifact_list(
        plugin_id: Annotated[str | None, typer.Option('--plugin-id', help='仅列出指定插件')] = None,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
    ) -> None:
        """
        查询已导入的制品列表。

        :param plugin_id: 插件 ID
        :param env: 当前命令运行环境
        :param output: 输出格式
        :return: None
        """
        get_controller().list_artifacts(env, output, plugin_id=plugin_id)

    @release_app.command('plan', help='静态预检制品维护计划，不执行迁移或Hook')
    def release_plan(
        plugin_id: Annotated[str, typer.Argument(help='插件ID')],
        digest: Annotated[str, typer.Argument(help='已导入制品的SHA256')],
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
    ) -> None:
        """
        查询目标制品的静态维护计划。

        :param plugin_id: 插件 ID
        :param digest: 已导入制品的 SHA256 摘要
        :param env: 当前命令运行环境
        :param output: 输出格式
        :return: None
        """
        get_controller().plan_release(plugin_id, digest, env, output)

    @release_app.command('prepare', help='停机维护执行安装或升级，成功后记录精确制品准备证据')
    def release_prepare(
        plugin_id: Annotated[str, typer.Argument(help='插件ID')],
        digest: Annotated[str, typer.Argument(help='已导入制品的SHA256')],
        maintenance: MaintenanceOption = False,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
        allow_prod: AllowProdOption = False,
        yes: YesOption = False,
        dry_run: DryRunOption = False,
    ) -> None:
        """
        在维护窗口准备指定制品的数据库与管理资源。

        :param plugin_id: 插件 ID
        :param digest: 已导入制品的 SHA256 摘要
        :param maintenance: 是否确认已停止全部宿主 worker 并进入维护窗口
        :param env: 当前命令运行环境
        :param output: 输出格式
        :param allow_prod: 是否允许生产环境危险命令
        :param yes: 是否跳过确认
        :param dry_run: 是否仅预演而不写入发布状态
        :return: None
        """
        get_controller().prepare_release(
            plugin_id, digest, env, output, maintenance=maintenance, allow_prod=allow_prod, yes=yes, dry_run=dry_run
        )

    @release_app.command('select', help='CAS选择已准备制品为目标，重启后由worker报告生效状态')
    def release_select(
        plugin_id: Annotated[str, typer.Argument(help='插件ID')],
        digest: Annotated[str, typer.Argument(help='已准备制品的SHA256')],
        expected_generation: ExpectedGenerationOption,
        expected_workers: Annotated[int, typer.Option('--expected-workers', min=1, help='预期宿主worker数量')] = 1,
        maintenance: MaintenanceOption = False,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
        allow_prod: AllowProdOption = False,
        yes: YesOption = False,
    ) -> None:
        """
        按预期发布代际选择已准备的目标制品。

        :param plugin_id: 插件 ID
        :param digest: 已导入制品的 SHA256 摘要
        :param expected_generation: 最近一次查询得到的发布代际，用于防止并发覆盖
        :param expected_workers: 发布完成时预期就绪的宿主 worker 数量
        :param maintenance: 是否确认已停止全部宿主 worker 并进入维护窗口
        :param env: 当前命令运行环境
        :param output: 输出格式
        :param allow_prod: 是否允许生产环境危险命令
        :param yes: 是否跳过确认
        :return: None
        """
        get_controller().select_release(
            plugin_id,
            digest,
            env,
            output,
            expected_generation=expected_generation,
            expected_workers=expected_workers,
            maintenance=maintenance,
            allow_prod=allow_prod,
            yes=yes,
        )

    @release_app.command('status', help='查询目标、数据库准备版本及各worker实际加载结果')
    def release_status(
        plugin_id: Annotated[str | None, typer.Option('--plugin-id', help='仅查询指定插件')] = None,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
    ) -> None:
        """
        查询制品发布状态及 worker 实际加载结果。

        :param plugin_id: 插件 ID
        :param env: 当前命令运行环境
        :param output: 输出格式
        :return: None
        """
        get_controller().release_status(env, output, plugin_id=plugin_id)

    @release_app.command('wait', help='只读等待指定摘要、代际和worker数量全部就绪；超时或失败返回非零')
    def release_wait(
        plugin_id: Annotated[str, typer.Argument(help='固定等待的插件ID')],
        digest: Annotated[str, typer.Argument(help='固定等待的64位小写SHA256摘要')],
        generation: Annotated[
            str, typer.Option('--generation', help='select、enable或rollback返回的新发布代际，32位小写十六进制')
        ],
        expected_workers: Annotated[int, typer.Option('--expected-workers', min=1, help='本次发布预期宿主worker数量')],
        timeout: Annotated[float, typer.Option('--timeout', min=0, help='轮询超时秒数，0表示只查询并断言一次')] = 300,
        interval: Annotated[float, typer.Option('--interval', help='两次查询间隔秒数，必须大于0')] = 2,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
    ) -> None:
        """
        等待精确发布目标就绪，只输出一次最终结果。

        :param plugin_id: 固定等待的插件 ID
        :param digest: 固定等待的制品 SHA256 摘要
        :param generation: 选择、启用或回滚目标后返回的新发布代际
        :param expected_workers: 本次发布要求的宿主 worker 数量
        :param timeout: 轮询超时秒数，为零时只查询一次
        :param interval: 查询间隔秒数
        :param env: 当前命令运行环境
        :param output: 输出格式
        :return: None
        """
        get_controller().wait_release(
            plugin_id,
            digest,
            env,
            output,
            expected_generation=generation,
            expected_workers=expected_workers,
            timeout_seconds=timeout,
            poll_interval_seconds=interval,
        )

    @release_app.command('rollback', help='选择上一个代码制品，保留当前数据库安装版本')
    def release_rollback(
        plugin_id: Annotated[str, typer.Argument(help='插件ID')],
        expected_generation: ExpectedGenerationOption,
        schema_compatible: Annotated[
            bool, typer.Option('--schema-compatible', help='确认旧代码兼容当前数据结构，不执行数据库回滚')
        ] = False,
        maintenance: MaintenanceOption = False,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
        allow_prod: AllowProdOption = False,
        yes: YesOption = False,
    ) -> None:
        """
        确认数据兼容后选择上一代码制品。

        :param plugin_id: 插件 ID
        :param expected_generation: 最近一次查询得到的发布代际，用于防止并发覆盖
        :param schema_compatible: 是否确认旧代码兼容当前数据结构
        :param maintenance: 是否确认已停止全部宿主 worker 并进入维护窗口
        :param env: 当前命令运行环境
        :param output: 输出格式
        :param allow_prod: 是否允许生产环境危险命令
        :param yes: 是否跳过确认
        :return: None
        """
        get_controller().rollback_release(
            plugin_id,
            env,
            output,
            expected_generation=expected_generation,
            schema_compatible=schema_compatible,
            maintenance=maintenance,
            allow_prod=allow_prod,
            yes=yes,
        )


def _register_release_enablement(app: typer.Typer, get_controller: Callable[[], Any]) -> None:
    """
    注册维护窗口内使用的制品启停命令。

    :param app: Typer 命令组
    :param get_controller: 制品命令控制器工厂
    :return: None
    """

    @app.command('enable', help='维护启用目标制品并更新代际，重启后生效')
    def release_enable(
        plugin_id: Annotated[str, typer.Argument(help='插件ID')],
        expected_generation: ExpectedGenerationOption,
        maintenance: MaintenanceOption = False,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
        allow_prod: AllowProdOption = False,
        yes: YesOption = False,
    ) -> None:
        """
        在维护窗口启用目标制品，重启后生效。

        :param plugin_id: 插件 ID
        :param expected_generation: 最近一次查询得到的发布代际，用于防止并发覆盖
        :param maintenance: 是否确认已停止全部宿主 worker 并进入维护窗口
        :param env: 当前命令运行环境
        :param output: 输出格式
        :param allow_prod: 是否允许生产环境危险命令
        :param yes: 是否跳过确认
        :return: None
        """
        get_controller().set_release_enabled(
            plugin_id,
            env,
            output,
            enabled=True,
            expected_generation=expected_generation,
            maintenance=maintenance,
            allow_prod=allow_prod,
            yes=yes,
        )

    @app.command('disable', help='维护停用目标制品并更新代际，重启后生效')
    def release_disable(
        plugin_id: Annotated[str, typer.Argument(help='插件ID')],
        expected_generation: ExpectedGenerationOption,
        maintenance: MaintenanceOption = False,
        env: EnvOption = 'dev',
        output: OutputOption = 'text',
        allow_prod: AllowProdOption = False,
        yes: YesOption = False,
    ) -> None:
        """
        在维护窗口停用目标制品，重启后生效。

        :param plugin_id: 插件 ID
        :param expected_generation: 最近一次查询得到的发布代际，用于防止并发覆盖
        :param maintenance: 是否确认已停止全部宿主 worker 并进入维护窗口
        :param env: 当前命令运行环境
        :param output: 输出格式
        :param allow_prod: 是否允许生产环境危险命令
        :param yes: 是否跳过确认
        :return: None
        """
        get_controller().set_release_enabled(
            plugin_id,
            env,
            output,
            enabled=False,
            expected_generation=expected_generation,
            maintenance=maintenance,
            allow_prod=allow_prod,
            yes=yes,
        )