init http client using reflection by default

Aliorpse · Aliorpse · commit b98818454fe2 · 2025-09-20T19:38:07.000+08:00
diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@ A Kotlin-based Minecraft request library provides utility functions related to M
 ```kotlin
 dependencies {
     implementation("tech.aliorpse:mcutils:$version")
+    implementation("io.ktor:ktor-client-cio:$version") //or the client you want
 }
 ```
 
@@ -43,8 +44,6 @@ runBlocking {
 
 ```kotlin
 runBlocking {
-    McUtilsHttpClient.init(CIO)
-    
     var pl
     pl = Player.getProfile("Aliorpse")
     pl = Player.getProfile("ec042e1200ac4a249cc83eb1fab0bd88")
@@ -56,8 +55,6 @@ runBlocking {
 
 ```kotlin
 runBlocking {
-    McUtilsHttpClient.init(CIO)
-    
     var result
     result = Modrinth.search("xplus") {
         author = "Wudji"
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -37,6 +37,8 @@ dependencies {
     api("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
     api("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
 
+    api(kotlin("reflect"))
+
     api("io.ktor:ktor-client-core:3.3.0")
     api("io.ktor:ktor-client-content-negotiation:3.3.0")
     api("io.ktor:ktor-serialization-kotlinx-json:3.3.0")
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/model/modrinth/project/ModrinthProject.kt b/src/main/kotlin/tech/aliorpse/mcutils/model/modrinth/project/ModrinthProject.kt
@@ -2,11 +2,7 @@ package tech.aliorpse.mcutils.model.modrinth.project
 
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
-import tech.aliorpse.mcutils.model.modrinth.MonetizationStatus
-import tech.aliorpse.mcutils.model.modrinth.ProjectStatus
-import tech.aliorpse.mcutils.model.modrinth.ProjectType
-import tech.aliorpse.mcutils.model.modrinth.RequestedStatus
-import tech.aliorpse.mcutils.model.modrinth.SideSupport
+import tech.aliorpse.mcutils.model.modrinth.*
 
 @Serializable
 public data class ModrinthProject(
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/model/player/PlayerProfileSerializer.kt b/src/main/kotlin/tech/aliorpse/mcutils/model/player/PlayerProfileSerializer.kt
@@ -1,19 +1,14 @@
 package tech.aliorpse.mcutils.model.player
 
-import io.ktor.util.decodeBase64Bytes
+import io.ktor.util.*
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.descriptors.buildClassSerialDescriptor
 import kotlinx.serialization.descriptors.element
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 import kotlinx.serialization.encoding.encodeStructure
-import kotlinx.serialization.json.Json
-import kotlinx.serialization.json.JsonDecoder
-import kotlinx.serialization.json.booleanOrNull
-import kotlinx.serialization.json.jsonArray
-import kotlinx.serialization.json.jsonObject
-import kotlinx.serialization.json.jsonPrimitive
+import kotlinx.serialization.json.*
 
 public object PlayerProfileSerializer : KSerializer<PlayerProfile> {
     override val descriptor: SerialDescriptor =
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/model/server/JavaServerStatusSerializer.kt b/src/main/kotlin/tech/aliorpse/mcutils/model/server/JavaServerStatusSerializer.kt
@@ -6,11 +6,7 @@ import kotlinx.serialization.descriptors.buildClassSerialDescriptor
 import kotlinx.serialization.descriptors.element
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
-import kotlinx.serialization.json.JsonDecoder
-import kotlinx.serialization.json.booleanOrNull
-import kotlinx.serialization.json.contentOrNull
-import kotlinx.serialization.json.jsonObject
-import kotlinx.serialization.json.jsonPrimitive
+import kotlinx.serialization.json.*
 
 internal object JavaServerStatusSerializer : KSerializer<JavaServerStatus> {
     override val descriptor: SerialDescriptor =
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/model/server/TextComponentSerializer.kt b/src/main/kotlin/tech/aliorpse/mcutils/model/server/TextComponentSerializer.kt
@@ -6,13 +6,9 @@ import kotlinx.serialization.builtins.ListSerializer
 import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
-import kotlinx.serialization.json.JsonArray
-import kotlinx.serialization.json.JsonDecoder
-import kotlinx.serialization.json.JsonObject
-import kotlinx.serialization.json.JsonPrimitive
-import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.*
 import tech.aliorpse.mcutils.utils.toTextComponent
-import java.util.EnumSet
+import java.util.*
 
 internal object TextComponentSerializer : KSerializer<TextComponent> {
     @Serializable
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/modules/modrinth/Modrinth.kt b/src/main/kotlin/tech/aliorpse/mcutils/modules/modrinth/Modrinth.kt
@@ -1,14 +1,13 @@
 package tech.aliorpse.mcutils.modules.modrinth
 
-import io.ktor.client.call.body
-import io.ktor.client.request.get
-import io.ktor.client.request.parameter
+import io.ktor.client.call.*
+import io.ktor.client.request.*
 import love.forte.plugin.suspendtrans.annotation.JvmAsync
 import love.forte.plugin.suspendtrans.annotation.JvmBlocking
 import tech.aliorpse.mcutils.model.modrinth.project.ModrinthProject
 import tech.aliorpse.mcutils.model.modrinth.search.ModrinthSearchConfig
 import tech.aliorpse.mcutils.model.modrinth.search.ModrinthSearchResponse
-import tech.aliorpse.mcutils.utils.McUtilsHttpClient
+import tech.aliorpse.mcutils.utils.McUtilsHttpClientProvider
 import tech.aliorpse.mcutils.utils.withDispatchersIO
 
 /**
@@ -39,7 +38,7 @@ public object Modrinth {
                 inner.joinToString(prefix = "[", postfix = "]") { "\"$it\"" }
             }
 
-        McUtilsHttpClient.client.get("$API_BASE/v2/search") {
+        McUtilsHttpClientProvider.client.get("$API_BASE/v2/search") {
             parameter("query", query)
             parameter("facets", facetsStr)
             parameter("limit", cfg.limit)
@@ -56,7 +55,7 @@ public object Modrinth {
     @JvmBlocking
     public suspend fun getProjects(ids: List<String>): List<ModrinthProject> = withDispatchersIO {
         val idsStr = ids.joinToString(",", "[", "]") { "\"$it\"" }
-        McUtilsHttpClient.client.get("$API_BASE/v2/projects") {
+        McUtilsHttpClientProvider.client.get("$API_BASE/v2/projects") {
             parameter("ids", idsStr)
         }.body()
     }
@@ -81,7 +80,7 @@ public object Modrinth {
     @JvmBlocking
     public suspend fun getProjectsRandom(count: Int = 10): List<ModrinthProject> = withDispatchersIO {
         require(count <= 100)
-        McUtilsHttpClient.client.get("$API_BASE/v2/projects_random") {
+        McUtilsHttpClientProvider.client.get("$API_BASE/v2/projects_random") {
             parameter("count", count)
         }.body()
     }
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/modules/player/Player.kt b/src/main/kotlin/tech/aliorpse/mcutils/modules/player/Player.kt
@@ -1,12 +1,12 @@
 package tech.aliorpse.mcutils.modules.player
 
-import io.ktor.client.call.body
-import io.ktor.client.request.get
+import io.ktor.client.call.*
+import io.ktor.client.request.*
 import love.forte.plugin.suspendtrans.annotation.JvmAsync
 import love.forte.plugin.suspendtrans.annotation.JvmBlocking
 import tech.aliorpse.mcutils.model.player.PlayerProfile
 import tech.aliorpse.mcutils.model.player.PlayerUUIDProfile
-import tech.aliorpse.mcutils.utils.McUtilsHttpClient
+import tech.aliorpse.mcutils.utils.McUtilsHttpClientProvider
 import tech.aliorpse.mcutils.utils.withDispatchersIO
 
 /**
@@ -41,13 +41,13 @@ public object Player {
 
         when {
             pl.length == UUID_LENGTH -> {
-                McUtilsHttpClient.client.get("$MOJANG_SESSION_BASE/session/minecraft/profile/$pl").body()
+                McUtilsHttpClientProvider.client.get("$MOJANG_SESSION_BASE/session/minecraft/profile/$pl").body()
             }
 
             nameRegex.matches(pl) -> {
                 val uuidProfile: PlayerUUIDProfile =
-                    McUtilsHttpClient.client.get("$MOJANG_PROFILE_BASE/users/profiles/minecraft/$pl").body()
-                McUtilsHttpClient.client.get("$MOJANG_SESSION_BASE/session/minecraft/profile/${uuidProfile.id}").body()
+                    McUtilsHttpClientProvider.client.get("$MOJANG_PROFILE_BASE/users/profiles/minecraft/$pl").body()
+                McUtilsHttpClientProvider.client.get("$MOJANG_SESSION_BASE/session/minecraft/profile/${uuidProfile.id}").body()
             }
 
             else -> throw IllegalArgumentException("Invalid identifier: $pl")
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/modules/server/JavaServer.kt b/src/main/kotlin/tech/aliorpse/mcutils/modules/server/JavaServer.kt
@@ -1,27 +1,22 @@
 package tech.aliorpse.mcutils.modules.server
 
 
-import kotlinx.serialization.json.Json
 import kotlinx.io.IOException
+import kotlinx.serialization.json.Json
 import love.forte.plugin.suspendtrans.annotation.JvmAsync
 import love.forte.plugin.suspendtrans.annotation.JvmBlocking
-import org.xbill.DNS.AAAARecord
-import org.xbill.DNS.ARecord
-import org.xbill.DNS.CNAMERecord
-import org.xbill.DNS.Lookup
-import org.xbill.DNS.SRVRecord
-import org.xbill.DNS.Type
+import org.xbill.DNS.*
 import tech.aliorpse.mcutils.model.server.JavaServerStatus
-import tech.aliorpse.mcutils.utils.withDispatchersIO
-import java.net.IDN
-import java.net.InetSocketAddress
-import java.net.Socket
-import java.nio.charset.StandardCharsets
 import tech.aliorpse.mcutils.model.server.JavaServerStatusSerializer
+import tech.aliorpse.mcutils.utils.withDispatchersIO
 import java.io.ByteArrayOutputStream
 import java.io.DataInputStream
 import java.io.DataOutputStream
 import java.io.OutputStream
+import java.net.IDN
+import java.net.InetSocketAddress
+import java.net.Socket
+import java.nio.charset.StandardCharsets
 
 /**
  * Provides functionality to fetch and parse the status of a Java Minecraft server.
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/utils/McUtilsHttpClient.kt b/src/main/kotlin/tech/aliorpse/mcutils/utils/McUtilsHttpClient.kt
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/utils/McUtilsHttpClientProvider.kt b/src/main/kotlin/tech/aliorpse/mcutils/utils/McUtilsHttpClientProvider.kt
@@ -0,0 +1,92 @@
+package tech.aliorpse.mcutils.utils
+
+import io.ktor.client.*
+import io.ktor.client.engine.*
+import io.ktor.client.plugins.contentnegotiation.*
+import io.ktor.serialization.kotlinx.json.*
+import kotlinx.serialization.json.Json
+import tech.aliorpse.mcutils.utils.McUtilsHttpClientProvider.client
+import tech.aliorpse.mcutils.utils.McUtilsHttpClientProvider.use
+import kotlin.reflect.KProperty
+
+/**
+ * Provides the [HttpClient] used internally.
+ *
+ * By default, the client will be initialized lazily by detecting
+ * the first available engine on the classpath in the following order:
+ *
+ * - CIO
+ * - OkHttp
+ * - Jetty
+ * - Java
+ * - Apache5
+ *
+ * In most cases no configuration is required.
+ * To override this, call [use] before the first access.
+ *
+ * Example:
+ * ```kotlin
+ * McUtilsHttpClientProvider.use(OkHttp)
+ * ```
+ */
+public object McUtilsHttpClientProvider {
+    private val delegate = HttpClientDelegate()
+
+    internal val client: HttpClient by delegate
+
+    private fun makeClient(engine: HttpClientEngineFactory<*>): HttpClient =
+        HttpClient(engine) {
+            install(ContentNegotiation) {
+                json(Json {
+                    ignoreUnknownKeys = true
+                    isLenient = true
+                })
+            }
+        }
+
+    private class HttpClientDelegate {
+        private val availableClients = listOf(
+            "io.ktor.client.engine.cio.CIO",
+            "io.ktor.client.engine.okhttp.OkHttp",
+            "io.ktor.client.engine.jetty.Jetty",
+            "io.ktor.client.engine.java.Java",
+            "io.ktor.client.engine.apache5.Apache5",
+        )
+
+        @Volatile private var client: HttpClient? = null
+
+        operator fun getValue(thisRef: Any?, property: KProperty<*>): HttpClient {
+            client?.let { return it }
+
+            val initialized = synchronized(this) {
+                client?.let { return@synchronized it }
+
+                for (clientName in availableClients) {
+                    val clazz = runCatching { Class.forName(clientName) }.getOrNull() ?: continue
+                    val engine = clazz.kotlin.objectInstance as HttpClientEngineFactory<*>
+
+                    val newClient = makeClient(engine)
+                    client = newClient
+                    return@synchronized newClient
+                }
+
+                null
+            }
+
+            return initialized ?: error("No available ktor engine found in classpath")
+        }
+
+        fun setClient(value: HttpClient) {
+            if (client != null) error("HttpClient has already been initialized")
+            client = value
+        }
+    }
+
+    /**
+     * Overrides the default [HttpClient] with a custom engine.
+     *
+     * Must be called **before** the first access of [client], or you will get a [IllegalStateException],
+     * and it should be only called **once**.
+     */
+    public fun use(engine: HttpClientEngineFactory<*>): Unit = delegate.setClient(makeClient(engine))
+}
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/utils/TextComponent.kt b/src/main/kotlin/tech/aliorpse/mcutils/utils/TextComponent.kt
@@ -2,7 +2,7 @@ package tech.aliorpse.mcutils.utils
 
 import tech.aliorpse.mcutils.model.server.TextComponent
 import tech.aliorpse.mcutils.model.server.TextStyle
-import java.util.EnumSet
+import java.util.*
 
 /**
  * Coverts string with "§" to a [TextComponent].
diff --git a/src/test/kotlin/tech/aliorpse/mcutils/modrinth/Test.kt b/src/test/kotlin/tech/aliorpse/mcutils/modrinth/Test.kt
@@ -1,16 +1,13 @@
 package tech.aliorpse.mcutils.modrinth
 
-import io.ktor.client.engine.cio.CIO
 import kotlinx.coroutines.runBlocking
 import tech.aliorpse.mcutils.model.modrinth.ProjectType
 import tech.aliorpse.mcutils.modules.modrinth.Modrinth
-import tech.aliorpse.mcutils.utils.McUtilsHttpClient
 import kotlin.test.Test
 
 class Test {
     @Test
     fun searchTest() {
-        McUtilsHttpClient.init(CIO)
         val result = runBlocking {
             Modrinth.search("xplus") {
                 author = "Wudji"
@@ -23,7 +20,6 @@ class Test {
 
     @Test
     fun getProjectsTest() {
-        McUtilsHttpClient.init(CIO)
         val result = runBlocking {
             Modrinth.getProjects(listOf("2H1rLgy4", "fabric-api"))
         }
@@ -33,7 +29,6 @@ class Test {
 
     @Test
     fun getProjectsRandomTest() {
-        McUtilsHttpClient.init(CIO)
         val result = runBlocking {
             Modrinth.getProjectsRandom(6)
         }
diff --git a/src/test/kotlin/tech/aliorpse/mcutils/player/PlayerProfileTest.kt b/src/test/kotlin/tech/aliorpse/mcutils/player/PlayerProfileTest.kt
@@ -1,9 +1,7 @@
 package tech.aliorpse.mcutils.player
 
-import io.ktor.client.engine.cio.CIO
 import kotlinx.coroutines.runBlocking
 import tech.aliorpse.mcutils.modules.player.Player
-import tech.aliorpse.mcutils.utils.McUtilsHttpClient
 import kotlin.test.Test
 
 class PlayerProfileTest {
@@ -12,7 +10,6 @@ class PlayerProfileTest {
      */
     @Test
     fun getProfileTest() {
-        McUtilsHttpClient.init(CIO)
         val result = runBlocking { Player.getProfile("ec042e1200ac4a249cc83eb1fab0bd88") }
         println(result)
         assert(result.name.isNotEmpty())
diff --git a/src/test/kotlin/tech/aliorpse/mcutils/server/ServerStatusTest.kt b/src/test/kotlin/tech/aliorpse/mcutils/server/ServerStatusTest.kt
