Merge branch 'kotlin-1.6.10' into kotlin-1.6.10-release

v0.1.2-kotlin-1.6.10 release

README.md

@@ -1,4 +1,18 @@
 # Huanshankeji Kotlin Common
+
+[![Maven Central](https://img.shields.io/maven-central/v/com.huanshankeji/kotlin-common-core)](https://search.maven.org/search?q=g:com.huanshankeji%20a:kotlin-common-*)
+
 Huanshankeji's common code libraries in Kotlin
 
-These include a core library to extend the Kotlin language and its standard library, and extension libraries for various Kotlin and Java libraries such as [Λrrow](https://arrow-kt.io/), Coroutines ([docs here](https://kotlinlang.org/docs/coroutines-overview.html) and [repository here](https://github.com/Kotlin/kotlinx.coroutines)), [Exposed](https://github.com/JetBrains/Exposed), [Ktor](https://ktor.io/), Serialization([docs here](https://kotlinlang.org/docs/serialization.html) and [repository here](https://github.com/Kotlin/kotlinx.serialization)), [Vert.x](https://vertx.io/), etc.
+These include a core library to extend the Kotlin language and its standard library, and extension libraries for various
+Kotlin and Java libraries such as [Λrrow](https://arrow-kt.io/),
+Coroutines ([docs here](https://kotlinlang.org/docs/coroutines-overview.html)
+and [repository here](https://github.com/Kotlin/kotlinx.coroutines)), [Exposed](https://github.com/JetBrains/Exposed)
+, [Ktor](https://ktor.io/), Serialization([docs here](https://kotlinlang.org/docs/serialization.html)
+and [repository here](https://github.com/Kotlin/kotlinx.serialization)), [Vert.x](https://vertx.io/), etc.
+
+## Maven coordinates
+
+```kotlin
+"com.huanshankeji:kotlin-common-$module:$version"
+```

buildSrc/src/main/kotlin/Versions.kt

@@ -1,5 +1,5 @@
 import com.huanshankeji.DefaultVersions
 
-val projectVersion = "0.1.1-kotlin-1.6.10"
+val projectVersion = "0.1.2-kotlin-1.6.10"
 
 val kotlinVersion = DefaultVersions.kotlin

vertx/build.gradle.kts

@@ -1,4 +1,5 @@
 import com.huanshankeji.CommonDependencies
+import com.huanshankeji.DefaultVersions
 
 plugins {
     id("jvm-conventions")
@@ -25,4 +26,20 @@ dependencies {
 
     implementation(project(":core"))
     implementation(project(":coroutines"))
+
+    testImplementation(kotlin("test"))
+    testImplementation(CommonDependencies.Kotlinx.Coroutines.test())
+    testImplementation(platform("org.junit:junit-bom:${DefaultVersions.junitJupiter}"))
+    testImplementation("org.junit.jupiter:junit-jupiter")
+    with(CommonDependencies.Vertx) {
+        testImplementation(moduleWithoutVersion("unit"))
+        testImplementation(moduleWithoutVersion("junit5"))
+        //testImplementation("io.vertx", "vertx-web", classifier = "tests") // This does not work well.
+        testImplementation(moduleWithoutVersion("web-client"))
+    }
+}
+
+kotlin.sourceSets["test"].languageSettings {
+    optIn("kotlin.RequiresOptIn")
+    optIn("kotlinx.coroutines.ExperimentalCoroutinesApi")
 }

vertx/src/main/kotlin/com/huanshankeji/vertx/Web.kt

@@ -3,31 +3,9 @@ package com.huanshankeji.vertx
 import io.netty.handler.codec.http.HttpResponseStatus.FORBIDDEN
 import io.netty.handler.codec.http.HttpResponseStatus.UNAUTHORIZED
 import io.vertx.ext.web.RoutingContext
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.CoroutineStart
-import kotlinx.coroutines.launch
-import kotlin.coroutines.CoroutineContext
-import kotlin.coroutines.EmptyCoroutineContext
 
 fun RoutingContext.failWithUnauthorized() =
     fail(UNAUTHORIZED.code())
 
 fun RoutingContext.failWithForbidden() =
     fail(FORBIDDEN.code())
-
-inline fun RoutingContext.checkedRun(block: () -> Unit): Unit =
-    try {
-        block()
-    } catch (t: Throwable) {
-        fail(t)
-    }
-
-inline fun CoroutineScope.launchChecked(
-    ctx: RoutingContext,
-    context: CoroutineContext = EmptyCoroutineContext,
-    start: CoroutineStart = CoroutineStart.DEFAULT,
-    crossinline block: suspend CoroutineScope.() -> Unit
-) =
-    launch(context, start) {
-        ctx.checkedRun { block() }
-    }

vertx/src/main/kotlin/com/huanshankeji/vertx/ext/web/RoutingContext.kt

@@ -0,0 +1,13 @@
+package com.huanshankeji.vertx.ext.web
+
+import io.vertx.ext.web.RoutingContext
+
+/**
+ * Runs the [block] and calls [RoutingContext.fail] if a [Throwable] is thrown.
+ */
+inline fun RoutingContext.checkedRun(block: () -> Unit): Unit =
+    try {
+        block()
+    } catch (t: Throwable) {
+        fail(t)
+    }

vertx/src/main/kotlin/com/huanshankeji/vertx/ext/web/VirtualHostCombinable.kt

@@ -1,7 +1,20 @@
 package com.huanshankeji.vertx.ext.web
 
+import io.vertx.core.Verticle
 import io.vertx.ext.web.Router
 
 interface VirtualHostCombinable {
     fun Router.routesOnVirtualHost()
-}
+}
+
+interface SingleVirtualHostVerticle : VirtualHostCombinable, Verticle {
+    override fun Router.routesOnVirtualHost() {
+        mountSubRouter("/", subRouter()).virtualHost(virtualHost)
+    }
+
+    val virtualHost: String
+
+    fun subRouter(): Router = Router.router(vertx).apply { virtualHostSubRouter() }
+
+    fun Router.virtualHostSubRouter()
+}

vertx/src/main/kotlin/com/huanshankeji/vertx/kotlin/coroutines/VertxCoroutine.kt

@@ -1,22 +1,64 @@
 package com.huanshankeji.vertx.kotlin.coroutines
 
 import com.huanshankeji.kotlin.use
+import io.vertx.core.Future
+import io.vertx.core.Promise
 import io.vertx.core.Vertx
 import io.vertx.kotlin.coroutines.await
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.CoroutineStart
 import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.launch
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
 
+/**
+ * Execute the [block] code and close the [Vertx] instance like [kotlin.use] on an [AutoCloseable].
+ */
 suspend inline fun <R> Vertx.use(block: (Vertx) -> R): R =
-    use(block) { close().await() }
+    @Suppress("MoveLambdaOutsideParentheses")
+    use(block, { close().await() })
 
+/**
+ * Execute [blockingCode] that returns the a [T] instance with [Vertx.executeBlocking]
+ * and awaits its completion.
+ *
+ * Compared to [Vertx.executeBlocking]'s `blockingCodeHandler` argument,
+ * [blockingCode] returns the result when the operation completes instead of calling [Promise.complete].
+ */
 suspend fun <T> Vertx.awaitExecuteBlocking(blockingCode: () -> T): T =
     executeBlocking<T> {
         it.complete(blockingCode())
     }.await()
 
+/**
+ * Like [awaitExecuteBlocking] but [blockingCode] is a suspend function.
+ */
+@Suppress("DeprecatedCallableAddReplaceWith")
+@Deprecated("This implementation is buggy. See https://github.com/vert-x3/vertx-lang-kotlin/pull/222/commits/fc3c5c5cc0c572eaddb3c2c37d07c696f75b4443#diff-162b76dc534138518a237d9a8ed527f1b3ecaca67385ea7d4357b6eff203f699R138-R217 for a fixed proposed version.")
 suspend fun <T> Vertx.awaitSuspendExecuteBlocking(blockingCode: suspend () -> T): T =
     coroutineScope {
         executeBlocking<T> {
             launch { it.complete(blockingCode()) }
         }.await()
     }
+
+/**
+ * Launch a coroutine and converts it into a [Future]
+ * that completes when the suspended function returns and fails if it throws.
+ */
+fun <T> CoroutineScope.coroutineToFuture(
+    context: CoroutineContext = EmptyCoroutineContext,
+    start: CoroutineStart = CoroutineStart.DEFAULT,
+    block: suspend CoroutineScope.() -> T
+): Future<T> {
+    val promise = Promise.promise<T>()
+    launch(context, start) {
+        try {
+            promise.complete(block())
+        } catch (t: Throwable) {
+            promise.fail(t)
+        }
+    }
+    return promise.future()
+}

vertx/src/main/kotlin/com/huanshankeji/vertx/kotlin/coroutines/ExtendedCoroutineVerticle.kt → vertx/src/main/kotlin/com/huanshankeji/vertx/kotlin/coroutines/ext/web/ExtendedWebCoroutineVerticle.kt

@@ -1,23 +1,38 @@
-package com.huanshankeji.vertx.kotlin.coroutines
+package com.huanshankeji.vertx.kotlin.coroutines.ext.web
 
-import com.huanshankeji.vertx.checkedRun
+import com.huanshankeji.vertx.ext.web.checkedRun
+import com.huanshankeji.vertx.kotlin.coroutines.CoroutineVerticleI
 import io.vertx.ext.web.Route
 import io.vertx.ext.web.RoutingContext
 import io.vertx.kotlin.coroutines.CoroutineVerticle
 import kotlinx.coroutines.launch
 
-interface ExtendedCoroutineVerticleI : CoroutineVerticleI {
+interface ExtendedWebCoroutineVerticleI : CoroutineVerticleI {
+    /**
+     * Like [Route.handler] but with a suspend function as [requestHandler].
+     */
     fun Route.coroutineHandler(requestHandler: suspend (RoutingContext) -> Unit): Route =
         handler { launch { requestHandler(it) } }
 
+    /**
+     * Like [coroutineHandler] and calls [RoutingContext.fail] if a [Throwable] is thrown in [requestHandler].
+     */
     fun Route.checkedCoroutineHandler(requestHandler: suspend (RoutingContext) -> Unit): Route =
         coroutineHandler { ctx -> ctx.checkedRun { requestHandler(ctx) } }
 }
 
-abstract class ExtendedCoroutineVerticle : CoroutineVerticle(), ExtendedCoroutineVerticleI {
+abstract class ExtendedWebCoroutineVerticle : CoroutineVerticle(), ExtendedWebCoroutineVerticleI {
+    /**
+     * The inline version of [coroutineHandler],
+     * which might be slightly faster but can also make the stack trace difficult to debug.
+     */
     inline fun Route.coroutineHandlerInline(crossinline requestHandler: suspend (RoutingContext) -> Unit): Route =
         handler { launch { requestHandler(it) } }
 
+    /**
+     * The inline version of [checkedCoroutineHandler],
+     * which might be slightly faster but can also make the stack trace difficult to debug.
+     */
     inline fun Route.checkedCoroutineHandlerInline(crossinline requestHandler: suspend (RoutingContext) -> Unit): Route =
         coroutineHandlerInline { ctx -> ctx.checkedRun { requestHandler(ctx) } }
 

vertx/src/main/kotlin/com/huanshankeji/vertx/kotlin/coroutines/ext/web/RoutingContext.kt

@@ -0,0 +1,22 @@
+package com.huanshankeji.vertx.kotlin.coroutines.ext.web
+
+import com.huanshankeji.vertx.ext.web.checkedRun
+import io.vertx.ext.web.RoutingContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.CoroutineStart
+import kotlinx.coroutines.launch
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
+
+/**
+ * Launches a coroutine like [launch], and calls [RoutingContext.fail] on [ctx] if a [Throwable] is thrown in [block].
+ */
+inline fun CoroutineScope.launchChecked(
+    ctx: RoutingContext,
+    context: CoroutineContext = EmptyCoroutineContext,
+    start: CoroutineStart = CoroutineStart.DEFAULT,
+    crossinline block: suspend CoroutineScope.() -> Unit
+) =
+    launch(context, start) {
+        ctx.checkedRun { block() }
+    }

vertx/src/main/kotlin/com/huanshankeji/vertx/kotlin/ext/web/RoutingContext.kt

@@ -0,0 +1,12 @@
+package com.huanshankeji.vertx.kotlin.ext.web
+
+import io.vertx.ext.web.RoutingContext
+
+/**
+ * A `set` operator overloading extension function
+ * as idiomatic Kotlin syntactic sugar to [RoutingContext.put].
+ */
+@Suppress("NOTHING_TO_INLINE")
+inline operator fun RoutingContext.set(key: String, value: Any?) {
+    put(key, value)
+}

vertx/src/main/kotlin/com/huanshankeji/vertx/sqlclient/Tuple.kt

@@ -2,5 +2,8 @@ package com.huanshankeji.vertx.sqlclient
 
 import io.vertx.sqlclient.Tuple
 
+/**
+ * Converts a [Tuple] to a [List].
+ */
 fun Tuple.toList() =
     List(size()) { getValue(it) }

vertx/src/test/kotlin/com/huanshankeji/kotlinx/coroutines/test/TestScope.kt

@@ -0,0 +1,15 @@
+package com.huanshankeji.kotlinx.coroutines.test
+
+import kotlinx.coroutines.test.TestScope
+import kotlinx.coroutines.test.currentTime
+import kotlin.system.measureTimeMillis
+
+/**
+ * @see measureTimeMillis
+ * @see TestScope.currentTime
+ */
+inline fun TestScope.measureVirtualTime(block: () -> Unit): Long {
+    val start = currentTime
+    block()
+    return currentTime - start
+}

vertx/src/test/kotlin/com/huanshankeji/test/Constants.kt

@@ -0,0 +1,3 @@
+package com.huanshankeji.test
+
+const val DEFAULT_SLEEP_OR_DELAY_DURATION = 1000L

vertx/src/test/kotlin/com/huanshankeji/vertx/VertxBaseTest.kt

@@ -0,0 +1,19 @@
+package com.huanshankeji.vertx
+
+import io.vertx.core.Vertx
+import io.vertx.ext.unit.junit.RunTestOnContext
+import org.junit.Rule
+import kotlin.test.BeforeTest
+
+abstract class VertxBaseTest {
+    @Rule
+    @JvmField
+    val rule = RunTestOnContext()
+
+    protected lateinit var vertx: Vertx
+
+    @BeforeTest
+    fun initVertx() {
+        vertx = rule.vertx()
+    }
+}