内核生命周期加固施工单（Core Hardening）

package org.voidkit.core.core

import com.mojang.brigadier.CommandDispatcher
import net.minecraft.commands.CommandSourceStack
import net.minecraft.server.MinecraftServer
import org.voidkit.core.VoidkitCore
import org.voidkit.core.api.ApiRouter
import org.voidkit.core.api.Feature
import org.voidkit.core.api.FeatureState
import org.voidkit.core.config.VoidkitConfig
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.CopyOnWriteArrayList

/**
 * 功能模块注册表 —— 插件系统的唯一入口。
 *
 * ## 与旧版的关键区别
 *
 * 内核**不再硬编码**模块清单。每个插件在自己的 `@Mod` 构造里调 [register]，
 * 把自己的模块交进来。内核完全不知道有哪些插件存在，也不知道它们装了几个模块。
 *
 * 这让「装满所有模块」和「只装核心」跑的是同一条代码路径 —— 没有 if 判断某个来源
 * 在不在，只有「注册表里有几个模块」这一个事实。
 *
 * ## 注册时机
 *
 * [register] 是纯内存操作，可以在任何插件的构造期随时调用，**不需要等内核先初始化**。
 * 真正的启动动作（读配置、挂事件、注册命令）统一定在服务端启动阶段，见 [boot].
 *
 * ## 线程安全策略：写加锁、读快照
 *
 * 注册发生在 mod 构造期（FML 单线程），但 reload（`/vk reload`，服务器线程）会改写
 * 启用集合，Web API 线程又会并发读取注册表（见 `web` 模块 `ApiDefaults` 的
 * `/api/features`）。LinkedHashMap / ArrayList 都不是并发容器，「一边遍历一边 clear」
 * 会抛 ConcurrentModificationException。
 *
 * 所以：**写**操作统一进 [lock]（锁内只有纯内存操作，无 IO，不会长时间持锁）；
 * **读**操作一律拷贝快照；启用集合用 [activeSnapshot] 整体原子替换 ——
 * 正在跑的事件循环拿着旧列表跑完，新循环用新列表，读写互不阻塞。
 */
object PluginRegistry {

    /** 没标明来源时的默认归属。 */
    const val CORE_OWNER = "voidkit_core"

    /** 注册表写锁。 */
    private val lock = Any()

    private val all = LinkedHashMap<String, Feature>()
    private val owners = HashMap<String, String>()

    /**
     * 每个模块最近一次生命周期失败的原因（键不存在 = 正常）。
     *
     * 为什么需要它：模块失败不能只躺在日志里 —— `/vk features` 要把 FAILED 标出来，
     * 启动汇总也要报数，否则「模块启动失败」和「一切正常」在运维眼里没有区别（审计 CORE-012）。
     * 重新启用/重试成功时由 [step] 清除。
     */
    private val failures = ConcurrentHashMap<String, String>()

    /**
     * 当前启用的模块快照。
     *
     * reload 时**整体替换**而不是 clear()+add()：旧列表可能正被某个事件循环遍历，
     * 让它跑完；新循环看到的是完整的新列表，不会出现「半个新列表」。
     */
    @Volatile
    private var activeSnapshot: List<Feature> = emptyList()

    @Volatile
    private var booted = false

    /** RegisterCommandsEvent 先于 boot 触发时暂存的 dispatcher（见 registerCommands）。 */
    @Volatile
    private var pendingCommands: CommandDispatcher<CommandSourceStack>? = null

    /**
     * 启动钩子：各插件登记「内核 boot 完成后、命令注册之前」要做的事（通常是读自己的配置）。
     *
     * ## 为什么不让插件直接监听加载器的「服务端即将启动」事件
     *
     * 插件读配置的前提是「内核已经建好配置根目录、初始化了
     * [org.voidkit.core.util.ConfigFiles]」—— 这是个**顺序要求**。而加载器事件回调的顺序
     * **不由我们控制**：
     *  - 本分支（NeoForge 1.21.1）历史上靠给内核的监听标 `EventPriority.HIGHEST`
     *    把内核排到最前（见 `NeoForgeLifecycleBridge`）。那是**靠优先级硬撑**出来的顺序，
     *    并没有写进任何契约 —— 只要以后有别的注册路径插入，或者换到没有优先级的加载器，就会破。
     *  - **Fabric 就没有事件优先级**。2026-10-13 的 Fabric 分支实测：四个插件的 entrypoint
     *    跑在内核**前面**，插件回调里的 `ConfigFiles.resolve` 直接抛
     *    `IllegalStateException: ConfigFiles 尚未初始化（rootDir 未设置）`，服务端起不来。
     *
     * 所以把时机收回内核自己手里：插件登记钩子，内核在 [boot] 里按登记顺序调用。
     * 顺序由**内核的代码顺序**保证，而不是由加载器的派发语义保证 —— 这套机制
     * **与加载器无关**，NeoForge / Fabric 两条线用同一套，不再需要优先级。
     */
    private val bootHooks = CopyOnWriteArrayList<Pair<String, () -> Unit>>()

    /** 登记一个启动钩子。`owner` 只用于失败时的日志归属。 */
    fun onBoot(owner: String, block: () -> Unit) {
        bootHooks += owner to block
    }

    fun isBooted(): Boolean = booted

    /**
     * 登记一个功能模块。由各插件的 `@Mod` 构造调用。
     *
     * @param owner 该模块的来源标签（如 `voidkit_essentials`），仅用于面板分组显示，
     *              不要求它对应一个独立插件（合并后一个 jar 可提供多个来源标签）。
     */
    fun register(feature: Feature, owner: String = CORE_OWNER) {
        synchronized(lock) {
            if (all.containsKey(feature.id)) {
                LOG.error("重复的功能模块 id: {}（来自 {}），已忽略后者", feature.id, owner)
                return
            }
            all[feature.id] = feature
            owners[feature.id] = owner
        }
    }

    /**
     * 服务端即将启动时由内核调用：读配置 → 决定开关 → 挂事件总线。
     *
     * 放在这里而不是 mod 构造期，是为了让**构造期保持零 IO** —— 大型整合包里
     * 上百个 mod 并行加载，在构造期读文件会把启动时间拉长好几秒。
     */
    fun boot(config: VoidkitConfig, server: MinecraftServer) {
        if (booted) {
            LOG.warn("PluginRegistry 已经启动过一次，忽略重复调用")
            return
        }
        applyConfig(config)

        // ① 启用（onEnable）：配置打开的模块先启用。此刻命令还没注册，模块可以做准备。
        //    失败即出列（状态 FAILED）—— 坏模块不会拖垮整台服务器。
        val enabled = ArrayList<Feature>()
        activeSnapshot.forEach { feature ->
            if (feature.step(FeatureState.ENABLED, "启用") { feature.onEnable(server) }) {
                enabled.add(feature)
            }
        }
        activeSnapshot = enabled

        attachEventHandlers()
        aboutToStart(server)

        // 插件的配置加载：放在 aboutToStart 之后、命令注册之前。
        // 顺序由**本方法**保证，不再依赖加载器事件的派发顺序（见 onBoot 的说明）。
        runBootHooks()

        booted = true

        // 若 RegisterCommandsEvent 已先于 boot 触发（NeoForge 1.21.1 的时序），
        // 现在 active 已填好，补注册命令。
        pendingCommands?.let { doRegisterCommands(it) }
        pendingCommands = null

        val byOwner = pluginSummary()
        val failed = all().count { it.state == FeatureState.FAILED }
        LOG.info(
            "Voidkit 模块 {} / {} 已启用{}，按来源分组：{}",
            activeSnapshot.size, all().size,
            if (failed > 0) "，${failed} 个失败（/vk features 查看）" else "",
            byOwner.entries.joinToString(", ") { "${it.key}(${it.value})" },
        )
    }

    /** 依据配置刷新启用状态（reload 复用）。 */
    fun applyConfig(config: VoidkitConfig) {
        val next = ArrayList<Feature>(all.size)
        synchronized(lock) {
            all.values.forEach { feature ->
                val on = config.featureEnabled(feature.id, feature.defaultEnabled)
                feature.enabled = on
                if (on) next.add(feature)
            }
        }
        // 整体替换：旧列表可能正被事件循环遍历，让它跑完；新循环用新列表。
        activeSnapshot = next
    }

    /**
     * 事件挂载接入点（历史保留位）。
     *
     * VEvent 抽象（见 [dispatch]）落地后，Feature 的业务事件统一由框架翻译后经 [dispatch]
     * 逐个通知，**没有任何 Feature 再挂到加载器原生事件总线**，本方法因此是无害空实现。
     *
     * 保留它（而非删掉调用点）是为了不改变 [boot] / [reload] 的调用时序与可读性。
     */
    fun attachEventHandlers() {
        // 空实现：不再有模块挂到加载器事件总线（VEvent 已取代）。
    }

    /**
     * 通知已启用的模块：服务端即将启动，可以加载自己的配置了。
     *
     * 逐个走状态机：本阶段失败的模块出列 —— 不再注册它的命令、不会启动它。
     * 没有这套机制时，某模块启动失败会被静默吞掉、服务器却认为一切正常（审计 CORE-012）。
     */
    fun aboutToStart(server: MinecraftServer) {
        val ready = ArrayList<Feature>()
        activeSnapshot.forEach { feature ->
            if (feature.step(FeatureState.ENABLED, "启动准备") { feature.onServerAboutToStart(server) }) {
                ready.add(feature)
            }
        }
        activeSnapshot = ready
    }

    fun registerCommands(dispatcher: CommandDispatcher<CommandSourceStack>) {
        if (!booted) {
            // 🚨 NeoForge 1.21.1 实测：RegisterCommandsEvent 在 ServerAboutToStartEvent
            // （boot 填 active）**之前**触发。此时 active 还是空的，直接注册会一个命令都不注册。
            // 所以先暂存 dispatcher，等 boot 完成后再补注册（见 boot()）。
            pendingCommands = dispatcher
            return
        }
        doRegisterCommands(dispatcher)
    }

    private fun doRegisterCommands(dispatcher: CommandDispatcher<CommandSourceStack>) {
        LOG.info("[CMD] 注册命令，active 模块 = {}", activeSnapshot.map { it.id })
        activeSnapshot.forEach { feature ->
            runCatching { feature.registerCommands(dispatcher) }
                .onFailure { LOG.error("模块 {} 注册命令失败", feature.id, it) }
        }
    }

    fun registerApi(router: ApiRouter) {
        activeSnapshot.forEach { feature ->
            runCatching { feature.registerApi(router) }
                .onFailure { LOG.error("模块 {} 注册 API 失败", feature.id, it) }
        }
    }

    /**
     * ServerStarted：逐个启动。
     *
     * 启动失败的模块出列（状态 FAILED，记原因；可经 `/vk reload` 重试，见 [reload]）——
     * 否则它会以半初始化状态继续收 onSecond / 事件，问题更难查。
     */
    fun startAll(server: MinecraftServer) {
        val running = ArrayList<Feature>()
        activeSnapshot.forEach { feature ->
            if (feature.step(FeatureState.RUNNING, "启动") { feature.onServerStart(server) }) {
                running.add(feature)
            }
        }
        activeSnapshot = running
    }

    fun stopAll(server: MinecraftServer) = forEach("停止") { it.onServerStop(server) }

    fun tickSecond(server: MinecraftServer) = forEach("tick") { it.onSecond(server) }

    /**
     * 重载：按新配置 diff 出「新停用 / 新启用 / 保持」三类，分别走各自的生命周期。
     *
     * 旧实现只是 `applyConfig` + 全员 `onReload`：被关掉的模块没人停、没人回收，
     * 新打开的模块从没启动过 —— 资源泄漏和双实例问题的根源。现在：
     *
     * ```
     * reload
     *  ↓  applyConfig（重算开关，整体替换 activeSnapshot）
     * ① 新停用的：onServerStop → onDisable → destroy，状态 DISABLED
     * ② 新启用的（含上次失败待重试的）：onEnable → onServerStart → onReload，状态 RUNNING
     * ③ 保持启用的：onReload，状态 RUNNING
     * ```
     */
    fun reload(server: MinecraftServer) {
        val beforeIds = activeSnapshot.map { it.id }.toSet()
        applyConfig(VoidkitCore.config)
        val candidates = activeSnapshot
        val afterIds = candidates.map { it.id }.toSet()

        // ① 被关掉的模块：停 → 回收 → 置 DISABLED。之后它收不到任何回调。
        all().filter { it.id in beforeIds && it.id !in afterIds }.forEach { feature ->
            feature.step(FeatureState.DISABLED, "停用") {
                feature.onServerStop(server)
                feature.onDisable(server)
                feature.destroy()
            }
        }

        // ②③ 仍然/刚刚在列的模块：新的补完整启动，旧的只做热更新。失败的出列。
        val next = ArrayList<Feature>(candidates.size)
        candidates.forEach { feature ->
            val fresh = feature.id !in beforeIds || feature.state == FeatureState.FAILED
            val ok = if (fresh) {
                // 它的 onServerStart 从没被调用过（启动时它不在列），必须补一次
                feature.step(FeatureState.RUNNING, "启用并启动") {
                    feature.onEnable(server)
                    feature.onServerStart(server)
                    feature.onReload(server)
                }
            } else {
                feature.step(FeatureState.RUNNING, "重载") { feature.onReload(server) }
            }
            if (ok) next.add(feature)
        }
        activeSnapshot = next
    }

    private inline fun forEach(action: String, block: (Feature) -> Unit) {
        activeSnapshot.forEach { feature ->
            runCatching { block(feature) }
                .onFailure { LOG.error("模块 {} {}失败", feature.id, action, it) }
        }
    }

    /** 按登记顺序调用启动钩子；单个插件抛异常不影响其它插件。 */
    private fun runBootHooks() {
        bootHooks.forEach { (owner, block) ->
            runCatching(block).onFailure { LOG.error("{} 的启动钩子失败（配置可能未加载）", owner, it) }
        }
    }

    /**
     * 把事件分发给所有已启用模块（VEvent 抽象的核心）。
     *
     * 由 platform 层的 EventBridge 调用：它把加载器原生事件翻译成 VEvent 后，
     * 通过本方法逐个通知 active 模块的对应回调。单个模块抛异常不影响其它模块。
     */
    fun dispatch(block: (Feature) -> Unit) {
        activeSnapshot.forEach { feature ->
            runCatching { block(feature) }
                .onFailure { LOG.error("模块 {} 事件处理失败", feature.id, it) }
        }
    }

    /**
     * 执行一次生命周期动作：成功切到 [ok] 状态；异常记 FAILED 与原因，返回 false。
     *
     * 为什么模块级仍然 catch Throwable：一个坏模块不能炸掉整台服务器，这是刻意的隔离。
     * 要分级的是**内核级**失败（配置加载等，见 `VoidkitCore.loadConfig`），不在这里。
     */
    private fun Feature.step(ok: FeatureState, action: String, block: () -> Unit): Boolean {
        return try {
            block()
            state = ok
            failures.remove(id)
            true
        } catch (t: Throwable) {
            state = FeatureState.FAILED
            failures[id] = t.message ?: t.javaClass.simpleName
            LOG.error("模块 {} {}失败", id, action, t)
            false
        }
    }

    fun all(): List<Feature> = synchronized(lock) { all.values.toList() }

    fun active(): List<Feature> = activeSnapshot

    fun byId(id: String): Feature? = synchronized(lock) { all[id] }

    fun ownerOf(featureId: String): String = synchronized(lock) { owners[featureId] } ?: CORE_OWNER

    /** 来源标签 -> 该来源提供的模块数。面板用。 */
    fun pluginSummary(): Map<String, Int> = synchronized(lock) { owners.values.groupingBy { it }.eachCount() }

    private val LOG get() = VoidkitCore.LOG
}

package org.voidkit.core.api

/**
 * 功能模块的生命周期状态。
 *
 * 为什么需要显式状态：reload（`/vk reload`）会改配置开关，框架必须分清每个模块
 * 「从没启动过」和「正在运行」，才能安全地关掉一个刚刚还被启用的模块
 * （回收它的缓存/任务/监听），或为刚被打开的模块补一次启动。
 * 一个 `enabled: Boolean` 分不清这两件事，reload 也就只能「全员 onReload」——
 * 资源泄漏和双实例问题的根源（审计 CORE-001/011）。
 *
 * 状态迁移全部发生在服务器线程、且是同步的，所以不设 INITIALIZING 这类瞬时态。
 */
enum class FeatureState {
    /** 已构造，未启用。 */
    CREATED,

    /** 已启用，等待启动（onServerStart 尚未调用）。 */
    ENABLED,

    /** 运行中。 */
    RUNNING,

    /** 已停用并回收（destroy 已调用），等下一次启用。 */
    DISABLED,

    /** 启用/启动过程抛异常，模块不可用；可经 `/vk reload` 重试。 */
    FAILED,
}

    /** 由 [PluginRegistry] 按配置写入。 */
    var enabled: Boolean = false
        internal set

    /**
     * 当前生命周期状态。由框架（PluginRegistry）驱动，模块只读。
     *
     * 模块在自己的回调里可以用它做防御，例如 `if (state != FeatureState.RUNNING) return`。
     */
    var state: FeatureState = FeatureState.CREATED
        internal set

    /** 模块被启用时调用一次（配置打开、进入 active 集合）。默认无动作。 */
    open fun onEnable(server: MinecraftServer) {}

    /**
     * 模块被停用时调用一次（配置关闭、离开 active 集合）。
     * 应停止周期任务、取消注册监听 —— 与 [destroy] 的分工：这个还可以用 server。
     */
    open fun onDisable(server: MinecraftServer) {}

    /** 资源回收：停用或框架卸载时调用，应清缓存、停线程、删引用。默认无动作。 */
    open fun destroy() {}

        /** 由 [ServerLifecycle] 在服务端启动阶段调用（此时配置根目录已就绪）。 */
        fun loadConfig() {
            configSafeMode = false
            try {
                // ⚠️ 必须在改写文件**之前**留底 —— 旧版把各插件的配置都塞在这里，
                //    插件要靠这份留存把自己的初版配置从旧值生成出来（见 LegacyConfig）。
                LegacyConfig.capture()

                config = ConfigFiles.load(CORE_FILE, VoidkitConfig::class.java, ConfigComments.CORE) { VoidkitConfig() }
                // Gson 走 Unsafe 分配对象，Kotlin 的默认参数不生效 —— 加载后必须补一遍
                config.normalize()
                // 语言要在任何消息产生之前定下来
                VoidkitLang.setLocale(config.language)
                configFile = ConfigFiles.resolve(CORE_FILE)
                saveConfig()
                LOG.info("内核配置就绪：{}", configFile)
            } catch (e: Exception) {
                // 只吞 Exception：OutOfMemoryError / StackOverflowError 是 JVM 级故障，
                // 吞掉只会带着坏状态继续跑，必须照原样抛出、崩在明处（审计 CORE-018）。
                //
                // 配置损坏时**不阻断启动**：产品立场是「服务器必须能起来」，默认值都调过；
                // 但必须用 ERROR 级明确告知正在用默认配置，否则管理员会以为自己改的配置
                // 生效了（审计 CORE-006）。
                LOG.error(
                    "内核配置加载失败，本轮以默认配置运行（安全模式）——请检查 {} 是否为合法 JSONC：{}",
                    CORE_FILE, e.message
                )
                configSafeMode = true
            }
        }

        /**
         * 内核配置是否处于「安全模式」—— 最近一次加载失败、正在用默认值运行。
         *
         * `/vk status` 会显示它。加载成功时复位（见 [loadConfig]）。
         */
        var configSafeMode: Boolean = false
            private set

import org.voidkit.core.api.FeatureState

    private fun features(source: CommandSourceStack): Int {
        Msg.info(source, "===== 功能模块（${PluginRegistry.active().size}/${PluginRegistry.all().size}） =====")
        PluginRegistry.all().forEach { feature ->
            val mark = when {
                feature.state == FeatureState.FAILED -> "&c[失败]"
                feature.enabled -> "&a[开]"
                else -> "&7[关]"
            }
            val line = "$mark &f${feature.id} &7- ${feature.displayName}"
            Msg.text(source, line)
        }
        return 1
    }

        if (VoidkitCore.configSafeMode) {
            Msg.err(source, "⚠ 内核配置加载失败，正在以默认配置运行（安全模式）——请检查 voidkit/core/config.json")
        }

    /** 附加权限节点，独立于分组。 */
    var permissions: MutableList<String> = CopyOnWriteArrayList()

        if (permissions == null) permissions = CopyOnWriteArrayList()

    /** 记录一次 IP 访问，返回对应记录。 */
    fun recordIp(ip: String?, name: String?, now: Long): IpRecord? {
        if (ip.isNullOrBlank()) return null
        // check-then-act 必须整体锁住：Web API 线程（面板查询触发）与命令线程会并发调它
        synchronized(ips) {
            val existing = ips.firstOrNull { it.ip == ip }
            if (existing != null) {
                existing.touch(name, now)
                return existing
            }
            val record = IpRecord(ip, now, now, 1)
            if (!name.isNullOrBlank()) record.names.add(name)
            ips.add(record)
            return record
        }
    }

    fun addKnownName(name: String?) {
        if (name.isNullOrBlank() || name == lastName) return
        synchronized(knownNames) {
            if (!knownNames.contains(name)) knownNames.add(name)
        }
    }