Docs for 0.5.0 Release (#256)

Kotlin · Jan 24, 2025 · 335e4a6 · 335e4a6
1 parent 0fac7cc
commit 335e4a6
Show file tree

Hide file tree

Showing 21 changed files with 566 additions and 179 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -20,7 +20,7 @@ env:
   ALGOLIA_INDEX_NAME: 'prod_kotlin_rpc'
   ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}'
   CONFIG_JSON_PRODUCT: 'kotlinx-rpc'
-  CONFIG_JSON_VERSION: '0.4.0'
+  CONFIG_JSON_VERSION: '0.5.0'
 
 jobs:
   build:

diff --git a/README.md b/README.md
@@ -25,23 +25,36 @@ import kotlinx.rpc.annotations.Rpc
 @Rpc
 interface AwesomeService : RemoteService {
     suspend fun getNews(city: String): Flow<String>
+
+    suspend fun daysUntilStableRelese(): Int
 }
 ```
 In your server code define how to respond by simply implementing the service:
 ```kotlin
-class AwesomeServiceImpl(override val coroutineContext: CoroutineContext) : AwesomeService {
+class AwesomeServiceImpl(
+    val parameters: AwesomeParameters,
+    override val coroutineContext: CoroutineContext,
+) : AwesomeService {
     override suspend fun getNews(city: String): Flow<String> {
         return flow { 
             emit("Today is 23 degrees!")
             emit("Harry Potter is in $city!")
             emit("New dogs cafe has opened doors to all fluffy customers!")
         }
     }
+
+    override suspend fun daysUntilStableRelese(): Int {
+        retuen if (parameters.stable) 0 else {
+            parameters.daysUntilStable ?: error("Who says it will be stable?")
+        }
+    }
 }
 ```
 Then, choose how do you want your service to communicate. For example, you can use integration with [Ktor](https://ktor.io/):
 
 ```kotlin
+data class AwesomeParameters(val stable: Boolean, val daysUntilStable: Int?)
+
 fun main() {
     embeddedServer(Netty, 8080) {
         install(Krpc)
@@ -53,7 +66,9 @@ fun main() {
                     }
                 }
 
-                registerService<AwesomeService> { ctx -> AwesomeServiceImpl(ctx) }
+                registerService<AwesomeService> { ctx -> 
+                    AwesomeServiceImpl(AwesomeParameters(false, null), ctx) 
+                }
             }
         }
     }.start(wait = true)
@@ -71,8 +86,12 @@ val rpcClient = HttpClient { installKrpc() }.rpc {
     }
 }
 
+val service = rpcClient.withService<AwesomeService>()
+
+service.daysUntilStableRelese()
+
 streamScoped {
-    rpcClient.withService<AwesomeService>().getNews("KotlinBurg").collect { article ->
+    service.getNews("KotlinBurg").collect { article ->
         println(article)
     }
 }
@@ -92,7 +111,7 @@ Example of a setup in a project's `build.gradle.kts`:
 plugins {
     kotlin("multiplatform") version "2.1.0"
     kotlin("plugin.serialization") version "2.1.0"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.4.0"
+    id("org.jetbrains.kotlinx.rpc.plugin") version "0.5.0"
 }
 ```
 
@@ -107,15 +126,15 @@ And now you can add dependencies to your project:
 ```kotlin
 dependencies {
     // Client API
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.4.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.5.0")
     // Server API
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.4.0") 
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.5.0") 
     // Serialization module. Also, protobuf and cbor are provided
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.4.0") 
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.5.0") 
 
     // Transport implementation for Ktor
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.4.0")
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.4.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.5.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.5.0")
 
     // Ktor API
     implementation("io.ktor:ktor-client-cio-jvm:$ktor_version")

diff --git a/core/src/commonMain/kotlin/kotlinx/rpc/RpcEagerField.kt b/core/src/commonMain/kotlin/kotlinx/rpc/RpcEagerField.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package kotlinx.rpc
@@ -8,6 +8,10 @@ package kotlinx.rpc
  * The field marked with this annotation will be initialized with the service creation.
  */
 @Target(AnnotationTarget.PROPERTY)
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public annotation class RpcEagerField
 
 @Deprecated("Use RpcEagerField instead", ReplaceWith("RpcEagerField"), level = DeprecationLevel.ERROR)

diff --git a/core/src/commonMain/kotlin/kotlinx/rpc/UninitializedRpcFieldException.kt b/core/src/commonMain/kotlin/kotlinx/rpc/UninitializedRpcFieldException.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package kotlinx.rpc
@@ -18,6 +18,10 @@ public typealias UninitializedRPCFieldException = UninitializedRpcFieldException
  *
  * Use [awaitFieldInitialization] to await for the field initialization
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public class UninitializedRpcFieldException(serviceName: String, property: KProperty<*>) : Exception() {
     override val message: String = "${property.name} field of RPC service \"$serviceName\" in not initialized"
 }
diff --git a/core/src/commonMain/kotlin/kotlinx/rpc/awaitFieldInitialization.kt b/core/src/commonMain/kotlin/kotlinx/rpc/awaitFieldInitialization.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package kotlinx.rpc
@@ -27,6 +27,10 @@ import kotlin.reflect.KClass
  * @param getter function that returns the field of the context service to wait for.
  * @return service filed after it was initialized.
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public suspend fun <@Rpc T : Any, R> T.awaitFieldInitialization(getter: T.() -> R): R {
     val field = getter()
 
@@ -56,6 +60,10 @@ public suspend fun <@Rpc T : Any, R> T.awaitFieldInitialization(getter: T.() ->
  * @param T service type
  * @return specified service, after all of it's field were initialized.
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public suspend inline fun <@Rpc reified T : Any> T.awaitFieldInitialization(): T {
     return awaitFieldInitialization(T::class)
 }
@@ -79,6 +87,10 @@ public suspend inline fun <@Rpc reified T : Any> T.awaitFieldInitialization(): T
  * @param kClass [KClass] of the [T] type.
  * @return specified service, after all of it's field were initialized.
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public suspend fun <@Rpc T : Any> T.awaitFieldInitialization(kClass: KClass<T>): T {
     serviceDescriptorOf(kClass)
         .getFields(this)

diff --git a/core/src/commonMain/kotlin/kotlinx/rpc/descriptor/RpcServiceDescriptor.kt b/core/src/commonMain/kotlin/kotlinx/rpc/descriptor/RpcServiceDescriptor.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package kotlinx.rpc.descriptor
@@ -44,6 +44,10 @@ public interface RpcServiceDescriptor<@Rpc T : Any> {
     public val fqName: String
 
     @InternalRpcApi
+    @Deprecated(
+        "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+        level = DeprecationLevel.WARNING,
+    )
     public fun getFields(service: T): List<RpcDeferredField<*>>
 
     public fun getCallable(name: String): RpcCallable<T>?
@@ -68,6 +72,10 @@ public sealed interface RpcInvokator<@Rpc T : Any> {
     }
 
     @ExperimentalRpcApi
+    @Deprecated(
+        "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+        level = DeprecationLevel.WARNING,
+    )
     public fun interface Field<@Rpc T : Any> : RpcInvokator<T> {
         public fun call(service: T): Any?
     }

diff --git a/core/src/commonMain/kotlin/kotlinx/rpc/registerField.kt b/core/src/commonMain/kotlin/kotlinx/rpc/registerField.kt
@@ -1,5 +1,5 @@
 /*
- * Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
 package kotlinx.rpc
@@ -25,6 +25,10 @@ import kotlinx.rpc.internal.RpcFlow
  * @param serviceId id of the service, that made the call
  * @return Flow instance to be consumed.
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public fun <T> RpcClient.registerPlainFlowField(
     serviceScope: CoroutineScope,
     descriptor: RpcServiceDescriptor<*>,
@@ -46,6 +50,10 @@ public fun <T> RpcClient.registerPlainFlowField(
  * @param serviceId id of the service, that made the call
  * @return SharedFlow instance to be consumed.
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public fun <T> RpcClient.registerSharedFlowField(
     serviceScope: CoroutineScope,
     descriptor: RpcServiceDescriptor<*>,
@@ -67,6 +75,10 @@ public fun <T> RpcClient.registerSharedFlowField(
  * @param serviceId id of the service, that made the call
  * @return StateFlow instance to be consumed.
  */
+@Deprecated(
+    "Fields are deprecated, see https://kotlin.github.io/kotlinx-rpc/0-5-0.html",
+    level = DeprecationLevel.WARNING,
+)
 public fun <T> RpcClient.registerStateFlowField(
     serviceScope: CoroutineScope,
     descriptor: RpcServiceDescriptor<*>,

diff --git a/docs/pages/kotlinx-rpc/.idea/kotlinx-rpc.iml b/docs/pages/kotlinx-rpc/.idea/kotlinx-rpc.iml
diff --git a/docs/pages/kotlinx-rpc/.idea/modules.xml b/docs/pages/kotlinx-rpc/.idea/modules.xml
diff --git a/docs/pages/kotlinx-rpc/help-versions.json b/docs/pages/kotlinx-rpc/help-versions.json
@@ -1,3 +1,3 @@
 [
-  {"version":"0.4.0","url":"/kotlinx-rpc/0.4.0/","isCurrent":true}
+  {"version":"0.5.0","url":"/kotlinx-rpc/0.5.0/","isCurrent":true}
 ]
diff --git a/docs/pages/kotlinx-rpc/rpc.tree b/docs/pages/kotlinx-rpc/rpc.tree
@@ -14,8 +14,10 @@
     <toc-element topic="plugins.topic"/>
     <toc-element toc-title="Core concepts">
         <toc-element topic="services.topic"/>
+        <toc-element topic="service-descriptors.topic"/>
         <toc-element topic="rpc-clients.topic"/>
         <toc-element topic="rpc-servers.topic"/>
+        <toc-element topic="annotation-type-safety.topic"/>
     </toc-element>
     <toc-element toc-title="Protocols">
         <toc-element toc-title="kRPC">
@@ -24,8 +26,10 @@
             <toc-element topic="transport.topic"/>
         </toc-element>
     </toc-element>
+    <toc-element topic="strict-mode.topic"/>
     <toc-element topic="versions.topic"/>
     <toc-element toc-title="Migration guides">
+        <toc-element topic="0-5-0.topic"/>
         <toc-element topic="0-4-0.topic"/>
         <toc-element topic="0-3-0.topic"/>
         <toc-element topic="0-2-4.topic"/>