Merge pull request #1079 from simple-robot/init-bot-api

feat(bot): introduce `ConfigurableBot` and `InitializableBot` interfaces

Author: ForteScarlet

simbot-api/api/simbot-api.api

@@ -445,6 +445,10 @@ public final class love/forte/simbot/bot/Bots {
 	public static final fun startIn (Llove/forte/simbot/bot/Bot;Lkotlinx/coroutines/CoroutineScope;)Lkotlinx/coroutines/Job;
 }
 
+public abstract interface class love/forte/simbot/bot/ConfigurableBot : love/forte/simbot/bot/Bot {
+	public abstract fun getConfiguration ()Ljava/lang/Object;
+}
+
 public class love/forte/simbot/bot/ConflictBotException : love/forte/simbot/bot/BotException {
 	public fun <init> ()V
 	public fun <init> (Ljava/lang/String;)V
@@ -488,6 +492,15 @@ public abstract interface class love/forte/simbot/bot/GuildRelation {
 	public abstract synthetic fun guildCount (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 
+public abstract interface class love/forte/simbot/bot/InitializableBot : love/forte/simbot/bot/ConfigurableBot {
+	public abstract synthetic fun init (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun initAsync ()Ljava/util/concurrent/CompletableFuture;
+	public fun initBlocking ()Z
+	public fun initReserve ()Llove/forte/simbot/suspendrunner/reserve/SuspendReserve;
+	public abstract fun isInitialized ()Z
+	public abstract fun isInitializing ()Z
+}
+
 public abstract class love/forte/simbot/bot/JobBasedBot : love/forte/simbot/bot/Bot {
 	public fun <init> ()V
 	public fun cancel (Ljava/lang/Throwable;)V

simbot-api/src/commonMain/kotlin/love/forte/simbot/bot/Bot.kt

@@ -1,5 +1,5 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
@@ -27,7 +27,6 @@ package love.forte.simbot.bot
 
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
-import kotlinx.coroutines.NonCancellable.join
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.launch
 import love.forte.simbot.ability.CompletionAware
@@ -55,6 +54,16 @@ import kotlin.jvm.JvmName
  * 它们可以提供针对 [Guild]、[ChatGroup]、[Contact] 等常见行为对象的操作。
  * [Bot] 的实现者也许会根据不同的平台扩展这些行为类型或提供更多的行为类型。
  *
+ * ## 扩展类型
+ *
+ * 对于组件实现者来说，[Bot] 有一些具有特殊含义的额外拓展类型。
+ * 可参考:
+ * - [ConfigurableBot]
+ * - [InitializableBot]
+ *
+ * @see ConfigurableBot
+ * @see InitializableBot
+ *
  * @author ForteScarlet
  */
 public interface Bot : IDContainer, LifecycleAware, CompletionAware, CoroutineScope, BotRelations {

simbot-api/src/commonMain/kotlin/love/forte/simbot/bot/ConfigurableBot.kt

@@ -0,0 +1,52 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package love.forte.simbot.bot
+
+
+/**
+ * 一个拥有配置信息的 [Bot]。
+ * 配置信息的具体类型由实现者决定。
+ *
+ * 配置信息类可能是一个可变类型，当使用它构建 [Bot] 后，它理应不再被修改。
+ * 如果实现了 [InitializableBot]，则直到 [init][InitializableBot.init] 调用前，配置信息 [configuration] 中的信息可以被修改。
+ *
+ * 配置类的内容也许在上述要求“不可修改”的情况下进行修改时不会产生异常（例如在 [init][InitializableBot.init]后继续修改），
+ * 但是它的修改可能不会生效，或可能引发任何不可预知的错误或埋下隐患。
+ *
+ * ## 特殊含义
+ * [ConfigurableBot] 具有特殊含义，可能会在部分场景被判断并有特殊作用。
+ *
+ * @see Bot
+ * @see InitializableBot
+ *
+ * @since 4.13.0
+ *
+ * @author ForteScarlet
+ */
+public interface ConfigurableBot : Bot {
+    /**
+     * 当前 Bot 持有的配置信息。
+     */
+    public val configuration: Any
+}

simbot-api/src/commonMain/kotlin/love/forte/simbot/bot/InitializableBot.kt

@@ -0,0 +1,72 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package love.forte.simbot.bot
+
+import love.forte.simbot.suspendrunner.ST
+
+
+/**
+ * 一个可初始化的 [Bot]，使其用于**延迟初始化**的能力。
+ * 实现了 [InitializableBot] 的 Bot 类型约定，在 [init] 之前，
+ * 可以继续修改 Bot 中的一些可修改信息，例如Bot所提供的配置类等。
+ *
+ * ## 特殊含义
+ * [ConfigurableBot] 具有特殊含义，可能会在部分场景被判断并有特殊作用。
+ *
+ * - 在 Spring Boot 中，
+ *
+ * @since 4.13.0
+ *
+ * @author ForteScarlet
+ */
+public interface InitializableBot : ConfigurableBot {
+
+    /**
+     * 初始化当前的 bot。当初始化完成后，[isInitialized] 将会得到 `true`,
+     * 且 [configuration] 中的属性不应再被修改。
+     *
+     * [init] 同样会在 [start] 的过程中被自动初始化，因此不需要手动在 [start] 之前调用 [init]。
+     * 你只需要在只需要初始化而不启动 bot 的情况下主动调用 [init]。
+     *
+     * [init] 可以被重复调用，但最终效果是一致的 —— bot只会被初始化一次。
+     * 当初始化完成后，后续的其他调用会直接返回 `false`。[init] 内部需通过锁或其他手段来保证这一点。
+     * 当 [init] 尚在初始化过程中持有锁时，[isInitializing] 将会得到 `true`。
+     *
+     * @return 如果本次初始化成功，则得到 `true`, 如果已经初始化过了，则得到 `false`。
+     */
+    @ST
+    public suspend fun init(): Boolean
+
+    /**
+     * 当前 bot 是否已经完成初始化。
+     */
+    public val isInitialized: Boolean
+
+    /**
+     * 是否正在初始化。
+     * 当 [isInitialized] 为 `false` 且 [init] 内部正在进行初始化并持有锁时，
+     * [isInitializing] 得到 `false`。
+     */
+    public val isInitializing: Boolean
+}