feat: add SuspendCustomArgument for asynchronous command argument parsing

Author: twisti-dev

surf-api-velocity/surf-api-velocity-api/src/main/kotlin/dev/slne/surf/surfapi/velocity/api/command/args/SuspendCustomArgument.kt

@@ -0,0 +1,96 @@
+package dev.slne.surf.surfapi.velocity.api.command.args
+
+import com.mojang.brigadier.context.CommandContext
+import com.velocitypowered.api.command.CommandSource
+import dev.jorel.commandapi.CommandAPIHandler
+import dev.jorel.commandapi.arguments.Argument
+import dev.jorel.commandapi.arguments.CommandAPIArgumentType
+import dev.jorel.commandapi.executors.CommandArguments
+import kotlinx.coroutines.*
+import net.kyori.adventure.text.logger.slf4j.ComponentLogger
+
+/**
+ * Base class for custom CommandAPI arguments whose parsing logic is executed asynchronously
+ * using Kotlin coroutines.
+ *
+ * This abstraction allows implementing suspendable parsing logic while still integrating
+ * with CommandAPI's synchronous argument parsing pipeline by returning a [Deferred].
+ *
+ * @param T The final parsed argument type.
+ * @param B The base argument type produced by the underlying [Argument].
+ * @property base The underlying base argument used for initial parsing.
+ * @property scope The [CoroutineScope] used to execute the suspendable parsing logic.
+ */
+abstract class SuspendCustomArgument<T, B>(
+    private val base: Argument<B>,
+    private val scope: CoroutineScope = defaultScope
+) : Argument<Deferred<T>>(base.nodeName, base.rawType) {
+
+    /**
+     * Parses the argument asynchronously.
+     *
+     * This method is executed inside the provided [CoroutineScope] and may perform
+     * suspendable or asynchronous operations such as database lookups or network calls.
+     *
+     * Implementations should throw [com.mojang.brigadier.exceptions.CommandSyntaxException] / [dev.jorel.commandapi.exceptions.WrapperCommandSyntaxException]
+     * to signal a user-facing parsing error.
+     *
+     * @param info Contextual information about the argument being parsed.
+     * @return The parsed argument value.
+     */
+    abstract suspend fun CoroutineScope.parse(info: CustomArgumentInfo<B>): T
+
+    /**
+     * Synchronously invoked by CommandAPI to parse the argument.
+     *
+     * Internally, this method delegates to [parse] by launching a coroutine in [scope]
+     * and returning a [Deferred] representing the eventual parsing result.
+     *
+     * @param cmdCtx The Brigadier command context.
+     * @param key The argument node name.
+     * @param previousArgs Previously parsed command arguments.
+     * @return A [Deferred] that completes with the parsed argument value.
+     */
+    final override fun <CommandSourceStack : Any> parseArgument(
+        cmdCtx: CommandContext<CommandSourceStack>,
+        key: String,
+        previousArgs: CommandArguments
+    ): Deferred<T> {
+        val customResult = CommandAPIHandler.getRawArgumentInput(cmdCtx, key)
+        val parsedInput = base.parseArgument(cmdCtx, key, previousArgs)
+
+        return scope.async {
+            val sender = cmdCtx.source as CommandSource
+            val info = CustomArgumentInfo(sender, previousArgs, customResult, parsedInput)
+            parse(info)
+        }
+    }
+
+    override fun getArgumentType(): CommandAPIArgumentType = base.argumentType
+
+    @JvmRecord
+    data class CustomArgumentInfo<B>(
+        val sender: CommandSource,
+        val previousArgs: CommandArguments,
+        val input: String,
+        val currentInput: B
+    )
+
+    companion object {
+        private val logger = ComponentLogger.logger()
+
+        private val defaultScopeExceptionHandler = CoroutineExceptionHandler { _, t ->
+            if (t is CancellationException) return@CoroutineExceptionHandler
+            logger.atError()
+                .setCause(t)
+                .log("Uncaught exception in command parsing coroutine")
+        }
+
+        private val defaultScope = CoroutineScope(
+            Dispatchers.IO.limitedParallelism(16) // We are not planning to do blocking work but preparing in case a developer messes up
+                    + SupervisorJob()
+                    + CoroutineName("Velocity Default Command Parsing Scope")
+                    + defaultScopeExceptionHandler
+        )
+    }
+}