HostPort utils & improve docs quality

Aliorpse · Aliorpse · commit 65277aef2394 · 2025-09-21T02:12:19.000+08:00
diff --git a/README.md b/README.md
@@ -12,7 +12,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
+    implementation("io.ktor:ktor-client-cio:$version") // or the client you want
 }
 ```
 
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -23,8 +23,7 @@ kotlin {
 
 suspendTransformPlugin {
     transformers {
-        addJvmBlocking()
-        addJvmAsync()
+        useJvmDefault()
     }
 }
 
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/modules/modrinth/Modrinth.kt b/src/main/kotlin/tech/aliorpse/mcutils/modules/modrinth/Modrinth.kt
@@ -7,7 +7,7 @@ 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.McUtilsHttpClientProvider
+import tech.aliorpse.mcutils.utils.McUtilsHttpClientProvider.httpClient
 import tech.aliorpse.mcutils.utils.withDispatchersIO
 
 /**
@@ -21,7 +21,6 @@ public object Modrinth {
      *
      * @param query Search query.
      * @param config Optional configuration for search parameters.
-     * @return [ModrinthSearchResponse] containing the search results.
      */
     @JvmStatic
     @JvmOverloads
@@ -38,7 +37,7 @@ public object Modrinth {
                 inner.joinToString(prefix = "[", postfix = "]") { "\"$it\"" }
             }
 
-        McUtilsHttpClientProvider.client.get("$API_BASE/v2/search") {
+        httpClient.get("$API_BASE/v2/search") {
             parameter("query", query)
             parameter("facets", facetsStr)
             parameter("limit", cfg.limit)
@@ -55,7 +54,7 @@ public object Modrinth {
     @JvmBlocking
     public suspend fun getProjects(ids: List<String>): List<ModrinthProject> = withDispatchersIO {
         val idsStr = ids.joinToString(",", "[", "]") { "\"$it\"" }
-        McUtilsHttpClientProvider.client.get("$API_BASE/v2/projects") {
+        httpClient.get("$API_BASE/v2/projects") {
             parameter("ids", idsStr)
         }.body()
     }
@@ -80,7 +79,7 @@ public object Modrinth {
     @JvmBlocking
     public suspend fun getProjectsRandom(count: Int = 10): List<ModrinthProject> = withDispatchersIO {
         require(count <= 100)
-        McUtilsHttpClientProvider.client.get("$API_BASE/v2/projects_random") {
+        httpClient.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
@@ -6,7 +6,7 @@ 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.McUtilsHttpClientProvider
+import tech.aliorpse.mcutils.utils.McUtilsHttpClientProvider.httpClient
 import tech.aliorpse.mcutils.utils.withDispatchersIO
 
 /**
@@ -30,7 +30,6 @@ public object Player {
      * - A valid Minecraft username (3–16 characters, letters, digits, and underscores).
      *
      * @param player The player's UUID or username.
-     * @return A [PlayerProfile] containing the player's UUID, username, skin, cape, and model type.
      * @throws IllegalArgumentException if the input is neither a valid UUID nor a valid username.
      */
     @JvmStatic
@@ -41,13 +40,13 @@ public object Player {
 
         when {
             pl.length == UUID_LENGTH -> {
-                McUtilsHttpClientProvider.client.get("$MOJANG_SESSION_BASE/session/minecraft/profile/$pl").body()
+                httpClient.get("$MOJANG_SESSION_BASE/session/minecraft/profile/$pl").body()
             }
 
             nameRegex.matches(pl) -> {
                 val uuidProfile: PlayerUUIDProfile =
-                    McUtilsHttpClientProvider.client.get("$MOJANG_PROFILE_BASE/users/profiles/minecraft/$pl").body()
-                McUtilsHttpClientProvider.client.get("$MOJANG_SESSION_BASE/session/minecraft/profile/${uuidProfile.id}").body()
+                    httpClient.get("$MOJANG_PROFILE_BASE/users/profiles/minecraft/$pl").body()
+                httpClient.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/BedrockServer.kt b/src/main/kotlin/tech/aliorpse/mcutils/modules/server/BedrockServer.kt
@@ -6,6 +6,7 @@ import tech.aliorpse.mcutils.model.server.BedrockServerStatus
 import tech.aliorpse.mcutils.model.server.GameMode
 import tech.aliorpse.mcutils.model.server.Players
 import tech.aliorpse.mcutils.model.server.Version
+import tech.aliorpse.mcutils.utils.HostPort
 import tech.aliorpse.mcutils.utils.toTextComponent
 import tech.aliorpse.mcutils.utils.withDispatchersIO
 import java.io.IOException
@@ -35,13 +36,11 @@ public object BedrockServer {
     private const val SERVER_INFO_OFFSET = 33
 
     /**
-     * Fetches the status of a Bedrock server.
+     * Fetches the Bedrock server status.
      *
-     * @param host The server hostname or IP.
+     * @param host The server host.
      * @param port The server port (default 19132).
      * @param timeout Timeout in milliseconds (default 2000ms).
-     * @return A [BedrockServerStatus] containing the parsed server information.
-     * @throws IOException If the server response is invalid or timed out.
      */
     @JvmStatic
     @JvmOverloads
@@ -108,4 +107,24 @@ public object BedrockServer {
             )
         }
     }
+
+    /**
+     * Fetches the Bedrock server status.
+     *
+     * @param hostPort As it named.
+     * @param timeout Timeout in milliseconds (default 2000ms).
+     * @throws IllegalArgumentException If host is null.
+     */
+    @JvmStatic
+    @JvmOverloads
+    @JvmAsync
+    @JvmBlocking
+    public suspend fun getStatus(
+        hostPort: HostPort,
+        timeout: Int = 2000
+    ): BedrockServerStatus = getStatus(
+        hostPort.host ?: throw IllegalArgumentException("The host is null."),
+        hostPort.port ?: 19132,
+        timeout
+    )
 }
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/modules/server/JavaServer.kt b/src/main/kotlin/tech/aliorpse/mcutils/modules/server/JavaServer.kt
@@ -8,11 +8,13 @@ import love.forte.plugin.suspendtrans.annotation.JvmBlocking
 import org.xbill.DNS.*
 import tech.aliorpse.mcutils.model.server.JavaServerStatus
 import tech.aliorpse.mcutils.model.server.JavaServerStatusSerializer
+import tech.aliorpse.mcutils.utils.HostPort
 import tech.aliorpse.mcutils.utils.withDispatchersIO
 import java.io.ByteArrayOutputStream
 import java.io.DataInputStream
 import java.io.DataOutputStream
 import java.io.OutputStream
+import java.lang.IllegalArgumentException
 import java.net.IDN
 import java.net.InetSocketAddress
 import java.net.Socket
@@ -33,13 +35,11 @@ public object JavaServer {
     private val json = Json { ignoreUnknownKeys = true }
 
     /**
-     * Fetch the Java server status.
+     * Fetches the Java server status.
      *
      * @param host The server host.
      * @param port The server port (default 25565).
      * @param timeout Timeout in milliseconds (default 2000ms).
-     * @return [JavaServerStatus] representing the server's status.
-     * @throws IOException If network or parsing fails.
      */
     @JvmStatic
     @JvmOverloads
@@ -85,6 +85,27 @@ public object JavaServer {
         }
     }
 
+    /**
+     * Fetches the Java server status.
+     *
+     * @param hostPort As it named.
+     * @param timeout Timeout in milliseconds (default 2000ms).
+     * @return [JavaServerStatus] representing the server's status.
+     * @throws IllegalArgumentException If host is null.
+     */
+    @JvmStatic
+    @JvmOverloads
+    @JvmAsync
+    @JvmBlocking
+    public suspend fun getStatus(
+        hostPort: HostPort,
+        timeout: Int = 2000
+    ): JavaServerStatus = getStatus(
+        hostPort.host ?: throw IllegalArgumentException("The host is null."),
+        hostPort.port ?: 25565,
+        timeout
+    )
+
     private fun resolveToIpOrHost(host: String, depth: Int = 5): String? {
         if (depth <= 0) return null
         try {
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/utils/HostPort.kt b/src/main/kotlin/tech/aliorpse/mcutils/utils/HostPort.kt
@@ -0,0 +1,40 @@
+package tech.aliorpse.mcutils.utils
+
+import java.net.IDN
+
+public data class HostPort(
+    val host: String?,
+    val port: Int?
+)
+
+/**
+ * Parses a host:port? string into [HostPort].
+ *
+ * - Empty input → HostPort(null, null)
+ * - Domains are normalized to punycode (IDN.toASCII)
+ * - Invalid ports → null
+ */
+public fun hostPortOf(address: String?): HostPort {
+    if (address.isNullOrBlank()) return HostPort(null, null)
+
+    return if (address.startsWith("[")) {
+        // IPv6
+        val closing = address.indexOf(']')
+        require(closing != -1) { "Invalid IPv6 address: $address" }
+        val host = address.substring(1, closing)
+        val port = address.substring(closing + 1)
+            .takeIf { it.startsWith(":") }
+            ?.drop(1)
+            ?.toIntOrNull()
+        HostPort(IDN.toASCII(host), port)
+    } else {
+        // IPv4 / domain
+        val parts = address.split(":", limit = 2)
+        val host = parts[0]
+        val port = parts.getOrNull(1)?.toIntOrNull()
+        HostPort(
+            host = IDN.toASCII(host),
+            port = port
+        )
+    }
+}
diff --git a/src/main/kotlin/tech/aliorpse/mcutils/utils/McUtilsHttpClientProvider.kt b/src/main/kotlin/tech/aliorpse/mcutils/utils/McUtilsHttpClientProvider.kt
@@ -5,7 +5,7 @@ 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.httpClient
 import kotlin.reflect.KProperty
 
 /**
@@ -31,7 +31,7 @@ import kotlin.reflect.KProperty
 public object McUtilsHttpClientProvider {
     private val delegate = HttpClientDelegate()
 
-    internal val client: HttpClient by delegate
+    internal val httpClient: HttpClient by delegate
 
     private fun makeClient(engine: HttpClientEngineFactory<*>): HttpClient =
         HttpClient(engine) {
@@ -84,8 +84,10 @@ public object McUtilsHttpClientProvider {
     /**
      * 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**.
+     * Must be called **before** the first access of [httpClient] (calling of http-related functions).
+     * It should be only called **once**.
+     *
+     * @throws IllegalStateException If called after the first access of [httpClient].
      */
     public fun use(engine: HttpClientEngineFactory<*>): Unit = delegate.setClient(makeClient(engine))
 }
diff --git a/src/test/kotlin/tech/aliorpse/mcutils/server/ServerStatusTest.kt b/src/test/kotlin/tech/aliorpse/mcutils/server/ServerStatusTest.kt
@@ -3,20 +3,21 @@ package tech.aliorpse.mcutils.server
 import kotlinx.coroutines.runBlocking
 import tech.aliorpse.mcutils.modules.server.BedrockServer
 import tech.aliorpse.mcutils.modules.server.JavaServer
+import tech.aliorpse.mcutils.utils.hostPortOf
 import kotlin.test.Test
 
 class ServerStatusTest {
     @Test
     fun javaGetStatusTest() {
-        val result = runBlocking { JavaServer.getStatus("wdsj.net") }
+        val result = runBlocking { JavaServer.getStatus(hostPortOf("wdsj.net")) }
 
         println(result)
         assert(result.version.protocol > 0)
     }
 
     @Test
     fun bedrockGetStatusTest() {
-        val result = runBlocking { BedrockServer.getStatus("asia.easecation.net") }
+        val result = runBlocking { BedrockServer.getStatus(hostPortOf("asia.easecation.net:19132")) }
 
         println(result)
         assert(result.ping > 0)

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ A Kotlin-based Minecraft request library provides utility functions related to M`
`12`	`12`	```kotlin
`13`	`13`	`dependencies {`
`14`	`14`	`implementation("tech.aliorpse:mcutils:$version")`
`15`		`- implementation("io.ktor:ktor-client-cio:$version") //or the client you want`
	`15`	`+ implementation("io.ktor:ktor-client-cio:$version") // or the client you want`
`16`	`16`	`}`
`17`	`17`	```
`18`	`18`
Original file line number	Diff line number	Diff line change
`@@ -23,8 +23,7 @@ kotlin {`
`23`	`23`
`24`	`24`	`suspendTransformPlugin {`
`25`	`25`	`transformers {`
`26`		`- addJvmBlocking()`
`27`		`- addJvmAsync()`
	`26`	`+ useJvmDefault()`
`28`	`27`	`}`
`29`	`28`	`}`
`30`	`29`