refactor: clarify package declarations; decouple logics

Author: Aliorpse

detekt.yml

@@ -3,3 +3,5 @@ buildUponDefaultConfig: true
 style:
   WildcardImport:
     active: false
+  MagicNumber:
+    active: false

…qqrev/saltify/core/SaltifyApplication.kt …rg/ntqqrev/saltify/SaltifyApplication.ktsaltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/core/SaltifyApplication.kt renamed to saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/SaltifyApplication.kt saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/core/SaltifyApplication.kt renamed to saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/SaltifyApplication.kt

@@ -1,45 +1,68 @@
-package org.ntqqrev.saltify.core
-
-import io.ktor.client.*
-import io.ktor.client.call.*
-import io.ktor.client.plugins.*
-import io.ktor.client.plugins.contentnegotiation.*
-import io.ktor.client.plugins.sse.*
-import io.ktor.client.plugins.websocket.*
-import io.ktor.client.request.*
-import io.ktor.http.*
-import io.ktor.serialization.kotlinx.*
-import io.ktor.serialization.kotlinx.json.*
-import io.ktor.util.logging.*
-import kotlinx.coroutines.*
-import kotlinx.coroutines.flow.*
+package org.ntqqrev.saltify
+
+import io.ktor.client.HttpClient
+import io.ktor.client.call.body
+import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
+import io.ktor.client.plugins.defaultRequest
+import io.ktor.client.plugins.sse.SSE
+import io.ktor.client.plugins.timeout
+import io.ktor.client.plugins.websocket.WebSockets
+import io.ktor.client.request.header
+import io.ktor.client.request.post
+import io.ktor.client.request.setBody
+import io.ktor.http.ContentType
+import io.ktor.http.HttpHeaders
+import io.ktor.http.contentType
+import io.ktor.serialization.kotlinx.KotlinxWebsocketSerializationConverter
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.util.logging.KtorSimpleLogger
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asSharedFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.job
+import kotlinx.coroutines.joinAll
+import kotlinx.coroutines.launch
 import kotlinx.serialization.json.decodeFromJsonElement
-import org.ntqqrev.milky.*
+import org.ntqqrev.milky.ApiEmptyStruct
+import org.ntqqrev.milky.ApiEndpoint
+import org.ntqqrev.milky.ApiGeneralResponse
+import org.ntqqrev.milky.Event
+import org.ntqqrev.milky.milkyJsonModule
 import org.ntqqrev.saltify.annotation.WithApiExtension
-import org.ntqqrev.saltify.dsl.SaltifyPluginContext
-import org.ntqqrev.saltify.dsl.config.SaltifyApplicationConfig
-import org.ntqqrev.saltify.entity.InstalledPlugin
-import org.ntqqrev.saltify.entity.RegisteredCommandInfo
+import org.ntqqrev.saltify.dsl.PluginBuilder
+import org.ntqqrev.saltify.dsl.config.ApplicationConfig
+import org.ntqqrev.saltify.internal.util.InstalledPlugin
+import org.ntqqrev.saltify.runtime.SaltifyComponent
+import org.ntqqrev.saltify.internal.util.ExceptionHandlerProvider
+import org.ntqqrev.saltify.runtime.command.RegisteredCommand
 import org.ntqqrev.saltify.exception.ApiCallException
-import org.ntqqrev.saltify.model.EventConnectionState
-import org.ntqqrev.saltify.model.EventConnectionType
+import org.ntqqrev.saltify.internal.app.SaltifyApplicationSSE
+import org.ntqqrev.saltify.internal.app.SaltifyApplicationWebSocket
 import org.ntqqrev.saltify.model.SaltifyComponentType
-import org.ntqqrev.saltify.util.coroutine.SaltifyComponent
-import org.ntqqrev.saltify.util.coroutine.SaltifyExceptionHandlerProvider
+import org.ntqqrev.saltify.model.event.EventConnectionState
+import org.ntqqrev.saltify.model.event.EventConnectionType
 import kotlin.coroutines.CoroutineContext
 import kotlin.time.Clock
 
 /**
  * 一个 Saltify 应用实例
  */
 @WithApiExtension
-public sealed class SaltifyApplication(@PublishedApi internal val config: SaltifyApplicationConfig) : AutoCloseable {
+public abstract class SaltifyApplication internal constructor(
+    @PublishedApi internal val config: ApplicationConfig
+) : AutoCloseable {
     public companion object {
         /**
          * 创建一个 Saltify 应用实例。
          */
-        public operator fun invoke(block: SaltifyApplicationConfig.() -> Unit): SaltifyApplication {
-            val config = SaltifyApplicationConfig().apply(block)
+        public operator fun invoke(block: ApplicationConfig.() -> Unit): SaltifyApplication {
+            val config = ApplicationConfig().apply(block)
             return when (config.connection.event.type) {
                 EventConnectionType.WebSocket -> SaltifyApplicationWebSocket(config)
                 EventConnectionType.SSE -> SaltifyApplicationSSE(config)
@@ -50,12 +73,12 @@ public sealed class SaltifyApplication(@PublishedApi internal val config: Saltif
     internal val logger = KtorSimpleLogger("Saltify/main")
 
     @PublishedApi
-    internal val exceptionHandlerProvider: SaltifyExceptionHandlerProvider = SaltifyExceptionHandlerProvider()
+    internal val exceptionHandlerProvider: ExceptionHandlerProvider = ExceptionHandlerProvider()
 
     /**
      * 全局异常流。
      *
-     * 可以通过 [SaltifyComponent] 判断异常抛出位置。
+     * 可以通过 [org.ntqqrev.saltify.runtime.SaltifyComponent] 判断异常抛出位置。
      *
      * ```kotlin
      * client.exceptionFlow.collect { (context, exception) ->
@@ -77,7 +100,7 @@ public sealed class SaltifyApplication(@PublishedApi internal val config: Saltif
 
     internal val applicationScope: CoroutineScope = CoroutineScope(
         SaltifyComponent(SaltifyComponentType.Application, "SaltifyApplication") +
-            exceptionHandlerProvider.handler
+                exceptionHandlerProvider.handler
     )
 
     protected val events: MutableSharedFlow<Event> = MutableSharedFlow(extraBufferCapacity = 64)
@@ -92,15 +115,15 @@ public sealed class SaltifyApplication(@PublishedApi internal val config: Saltif
     @PublishedApi
     internal val extensionScope: CoroutineScope = CoroutineScope(
         applicationScope.coroutineContext +
-            SupervisorJob(applicationScope.coroutineContext.job) +
-            SaltifyComponent(SaltifyComponentType.Extension, "SaltifyExtension")
+                SupervisorJob(applicationScope.coroutineContext.job) +
+                SaltifyComponent(SaltifyComponentType.Extension, "SaltifyExtension")
     )
 
     protected val addressBaseNormalized: String = config.connection.baseUrl.trimEnd('/')
 
-    private val loadedPlugins = mutableListOf<SaltifyPluginContext>()
+    private val loadedPlugins = mutableListOf<PluginBuilder>()
 
-    internal val commandRegistry: MutableList<RegisteredCommandInfo> = mutableListOf()
+    internal val commandRegistry: MutableList<RegisteredCommand> = mutableListOf()
 
     @PublishedApi
     internal val accessToken: String? = config.connection.accessToken
@@ -138,11 +161,11 @@ public sealed class SaltifyApplication(@PublishedApi internal val config: Saltif
 
             val pluginScope = CoroutineScope(
                 applicationScope.coroutineContext +
-                    SupervisorJob(applicationScope.coroutineContext.job) +
-                    SaltifyComponent(SaltifyComponentType.Plugin, plugin.name)
+                        SupervisorJob(applicationScope.coroutineContext.job) +
+                        SaltifyComponent(SaltifyComponentType.Plugin, plugin.name)
             )
 
-            val context = SaltifyPluginContext(plugin.name, this, pluginScope)
+            val context = PluginBuilder(this, pluginScope, plugin.name)
 
             plugin.setup(context, configInstance)
             loadedPlugins.add(context)

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/annotation/ContextParametersMigrationNeeded.kt

@@ -1,12 +1,13 @@
 package org.ntqqrev.saltify.builtin.plugin
 
-import org.ntqqrev.saltify.core.forward
-import org.ntqqrev.saltify.core.node
-import org.ntqqrev.saltify.core.text
 import org.ntqqrev.saltify.dsl.SaltifyPlugin
-import org.ntqqrev.saltify.entity.RegisteredCommandInfo
-import org.ntqqrev.saltify.entity.RegisteredSubCommandInfo
+import org.ntqqrev.saltify.runtime.command.RegisteredCommand
+import org.ntqqrev.saltify.runtime.command.RegisteredSubCommand
+import org.ntqqrev.saltify.extension.command
 import org.ntqqrev.saltify.extension.respond
+import org.ntqqrev.saltify.forward
+import org.ntqqrev.saltify.node
+import org.ntqqrev.saltify.text
 
 /**
  * Saltify 内置全局帮助指令插件。
@@ -49,7 +50,7 @@ public val commandHelp: SaltifyPlugin<Unit> = SaltifyPlugin("command-help") {
 
 private fun buildCommandGroupText(
     pluginName: String?,
-    commands: List<RegisteredCommandInfo>
+    commands: List<RegisteredCommand>
 ): String = buildString {
     if (pluginName != null) {
         appendLine("插件 $pluginName: ")
@@ -81,7 +82,7 @@ private fun buildCommandGroupText(
 }.trimEnd()
 
 private fun StringBuilder.appendSubCommand(
-    sub: RegisteredSubCommandInfo,
+    sub: RegisteredSubCommand,
     parentPath: String,
     depth: Int
 ) {

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/builtin/plugin/CommandHelp.kt

@@ -5,10 +5,11 @@ import kotlinx.coroutines.launch
 import org.ntqqrev.milky.Event
 import org.ntqqrev.milky.IncomingMessage
 import org.ntqqrev.saltify.dsl.SaltifyPlugin
+import org.ntqqrev.saltify.extension.on
 import org.ntqqrev.saltify.extension.plainText
-import org.ntqqrev.saltify.model.EventConnectionState
+import org.ntqqrev.saltify.model.event.EventConnectionState
 import org.ntqqrev.saltify.model.SaltifyComponentType
-import org.ntqqrev.saltify.util.coroutine.saltifyComponent
+import org.ntqqrev.saltify.runtime.saltifyComponent
 
 /**
  * Saltify 内置日志插件。
@@ -54,7 +55,7 @@ public val defaultLogging: SaltifyPlugin<Unit> = SaltifyPlugin("default-logging"
     }
 
     // 收到消息日志
-    on<Event.MessageReceive> { event ->
+    on<Event.MessageReceive> {
         when (val data = event.data) {
             is IncomingMessage.Group ->
                 logger.debug(

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/builtin/plugin/DefaultLogging.kt

@@ -0,0 +1,87 @@
+package org.ntqqrev.saltify.dsl
+
+import org.ntqqrev.saltify.annotation.SaltifyDsl
+import org.ntqqrev.saltify.runtime.command.CommandRequirementMatch
+import org.ntqqrev.saltify.runtime.command.CommandParameter
+import org.ntqqrev.saltify.runtime.context.CommandExecutionContext
+import org.ntqqrev.saltify.model.command.CommandError
+import org.ntqqrev.saltify.model.command.CommandRequirement
+
+@SaltifyDsl
+public class CommandBuilder internal constructor() {
+    public val parameter: SaltifyParameterBuilder = SaltifyParameterBuilder(this)
+
+    @PublishedApi
+    internal val parameters: MutableList<CommandParameter<*>> = mutableListOf()
+    internal val subCommands = mutableListOf<Pair<String, CommandBuilder>>()
+    internal var executionBlock: (suspend CommandExecutionContext.() -> Unit)? = null
+
+    /**
+     * 指令的描述信息。
+     */
+    public var description: String = ""
+
+    internal var groupExecutionBlock: (suspend CommandExecutionContext.() -> Unit)? = null
+    internal var privateExecutionBlock: (suspend CommandExecutionContext.() -> Unit)? = null
+    internal var failureBlock: (suspend CommandExecutionContext.(CommandError) -> Unit)? = null
+    internal var requirementBlock: (CommandRequirementMatch.() -> CommandRequirement)? = null
+
+    /**
+     * 注册一个子指令。
+     */
+    public fun subCommand(name: String, block: CommandBuilder.() -> Unit) {
+        subCommands.add(name to CommandBuilder().apply(block))
+    }
+
+    /**
+     * 定义指令执行要求。若不满足，静默返回。
+     */
+    public fun require(block: CommandRequirementMatch.() -> CommandRequirement) {
+        this.requirementBlock = block
+    }
+
+    /**
+     * 设置通用的指令执行逻辑。
+     */
+    public fun onExecute(block: suspend CommandExecutionContext.() -> Unit) {
+        executionBlock = block
+    }
+
+    /**
+     * 设置仅在群聊中触发的执行逻辑。优先级高于 [onExecute]，定义后在群聊不会使用 [onExecute]。
+     */
+    public fun onGroupExecute(block: suspend CommandExecutionContext.() -> Unit) {
+        groupExecutionBlock = block
+    }
+
+    /**
+     * 设置仅在私聊中触发的执行逻辑。优先级高于 [onExecute]，定义后在群聊不会使用 [onExecute]。
+     */
+    public fun onPrivateExecute(block: suspend CommandExecutionContext.() -> Unit) {
+        privateExecutionBlock = block
+    }
+
+    /**
+     * 当指令**解析**失败时执行的逻辑。
+     */
+    public fun onFailure(block: suspend CommandExecutionContext.(CommandError) -> Unit) {
+        failureBlock = block
+    }
+}
+
+public class SaltifyParameterBuilder(@PublishedApi internal val context: CommandBuilder) {
+    /**
+     * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
+     *
+     * @param isGreedy 是否是贪婪参数，即是否包含后面的所有剩余文本。
+     * @param transform 将原始文本转化为目标类型的函数。
+     */
+    public inline fun <reified T : Any> from(
+        name: String,
+        description: String,
+        isGreedy: Boolean = false,
+        noinline transform: (String) -> T?
+    ): CommandParameter<T> = CommandParameter(transform, T::class, name, description, isGreedy).also {
+            context.parameters.add(it)
+        }
+}

saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/CommandBuilder.kt

@@ -0,0 +1,68 @@
+package org.ntqqrev.saltify.dsl
+
+import io.ktor.util.logging.*
+import kotlinx.coroutines.CoroutineScope
+import org.ntqqrev.saltify.annotation.SaltifyDsl
+import org.ntqqrev.saltify.SaltifyApplication
+import org.ntqqrev.saltify.runtime.context.ApplicationContext
+
+@SaltifyDsl
+public class PluginBuilder internal constructor(
+    public override val client: SaltifyApplication,
+    @PublishedApi internal val pluginScope: CoroutineScope,
+    pluginName: String
+) : CoroutineScope by pluginScope, ApplicationContext(client) {
+    internal val onStartHooks = mutableListOf<suspend () -> Unit>()
+    internal val onStopHooks = mutableListOf<() -> Unit>()
+
+    public val logger: Logger = KtorSimpleLogger("Saltify/plugin:$pluginName")
+
+    /**
+     * 插件被加载，即 [SaltifyApplication.Companion.invoke] 后执行的逻辑。
+     */
+    public fun onStart(block: suspend () -> Unit) {
+        onStartHooks.add(block)
+    }
+
+    /**
+     * 插件被卸载，即 [SaltifyApplication.close] 前执行的逻辑。
+     */
+    public fun onStop(block: () -> Unit) {
+        onStopHooks.add(block)
+    }
+}
+
+/**
+ * 一个插件
+ */
+public class SaltifyPlugin<T : Any>(
+    public val name: String,
+    @PublishedApi internal val createConfig: () -> T,
+    internal val setup: PluginBuilder.(T) -> Unit
+) {
+    public companion object {
+        /**
+         * 创建一个插件。
+         *
+         * @param name 插件名，不填随机。
+         */
+        public operator fun <T : Any> invoke(
+            name: String = generateAnonymousName(),
+            config: () -> T,
+            setup: PluginBuilder.(config: T) -> Unit
+        ): SaltifyPlugin<T> = SaltifyPlugin(name, config, setup)
+
+        /**
+         * 创建一个插件。
+         *
+         * @param name 插件名，不填随机。
+         */
+        public operator fun invoke(
+            name: String = generateAnonymousName(),
+            setup: PluginBuilder.(Unit) -> Unit
+        ): SaltifyPlugin<Unit> = SaltifyPlugin(name, {}, setup)
+    }
+}
+
+private fun generateAnonymousName(): String =
+    "anonymous-${(1..4).map { ('A'..'Z').random() }.joinToString("")}"