Updated docs for 0.4.0; bumped version

.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.3.0'
+  CONFIG_JSON_VERSION: '0.4.0'
 
 jobs:
   build:

README.md

@@ -7,7 +7,7 @@
 
 [![Kotlin Experimental](https://kotl.in/badges/experimental.svg)](https://kotlinlang.org/docs/components-stability.html)
 [![Official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.7.0--2.0.10-blue.svg?logo=kotlin)](http://kotlinlang.org)
+[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0--2.0.21-blue.svg?logo=kotlin)](http://kotlinlang.org)
 [![GitHub License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)
 
 [//]: # ([![TeamCity build](https://img.shields.io/teamcity/build/s/Build_kRPC_All.svg?server=http%3A%2F%2Fkrpc.teamcity.com)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Build_kRPC_All&guest=1))
@@ -84,33 +84,18 @@ Check out our [getting started guide](https://kotlin.github.io/kotlinx-rpc) for
 
 ### Plugin dependencies
 
-`kotlinx.rpc` has the following plugin dependencies:
-- The `org.jetbrains.kotlinx.rpc.plugin` will set up BOM and code generation for targets in the project.
-- The `org.jetbrains.kotlinx.rpc.platform` will only set up BOM. It is useful when you want to split your app into modules, 
-and some of them will contain service declarations, thus using code generation, while others will only consume them.
+`kotlinx.rpc` provides Gradle plugin `org.jetbrains.kotlinx.rpc.plugin` 
+that will set up code generation in a project.
 
-Example of plugins setup in a project's `build.gradle.kts`:
+Example of a setup in a project's `build.gradle.kts`:
 ```kotlin
 plugins {
-    kotlin("jvm") version "2.0.10"
-    kotlin("plugin.serialization") version "2.0.10"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
+    kotlin("multiplatform") version "2.0.21"
+    kotlin("plugin.serialization") version "2.0.21"
+    id("org.jetbrains.kotlinx.rpc.plugin") version "0.4.0"
 }
 ```
 
-For Kotlin versions prior to 2.0, 
-KSP plugin is required 
-(Corresponding configurations will be set up automatically by `org.jetbrains.kotlinx.rpc.plugin` plugin):
-
-```kotlin
-// build.gradle.kts
-plugins {
-    kotlin("jvm") version "1.9.25"
-    kotlin("plugin.serialization") version "1.9.25"
-    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
-}
-```
 ### Runtime dependencies
 To use `kotlinx.rpc` runtime dependencies, add Maven Central to the list of your repositories: 
 ```kotlin
@@ -121,16 +106,16 @@ repositories {
 And now you can add dependencies to your project:
 ```kotlin
 dependencies {
-    // client API
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client")
-    // server API
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server") 
-    // serialization module. also, protobuf and cbor are available
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json") 
+    // Client API
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.4.0")
+    // Server API
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.4.0") 
+    // Serialization module. Also, protobuf and cbor are provided
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.4.0") 
 
-    // transport implementation for Ktor
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client")
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server")
+    // 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")
 
     // Ktor API
     implementation("io.ktor:ktor-client-cio-jvm:$ktor_version")
@@ -143,7 +128,7 @@ You can see example projects in the [samples](samples) folder.
 `kotlinx.rpc` is designed to be transport agnostic.
 That means that the library aims to provide the best RPC experience regardless of how the resulting messages are transferred. 
 That allows for easy integration into existing solutions, such as Ktor, without the need to rewrite code.
-Just plug-in `kotlinx.rpc`, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run.
+Add `kotlinx.rpc`, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run.
 With enough time it might even work with [avian carriers](https://en.wikipedia.org/wiki/IP_over_Avian_Carriers).
 
 `kotlinx.rpc` provides its own transfer protocol called kRPC, which takes responsibility for tracking serializing and handling other complex request operations.
@@ -154,26 +139,12 @@ Besides that, one can even provide their own protocol or integration with one to
 Though possible, it is much more complicated way to use the library and generally not needed. 
 `kotlinx.rpc` aims to provide most common protocols integrations as well as the in-house one called kRPC.  
 Integrations in progress:
-- Integration with [gRPC](https://grpc.io/)  (in prototype)
+- Integration with [gRPC](https://grpc.io/) (in prototype)
 
 ## Kotlin compatibility
 We support all stable Kotlin versions starting from 2.0.0:
 - 2.0.0, 2.0.10, 2.0.20, 2.0.21
 
-To simplify project configuration, our Gradle plugin sets a proper library version automatically using BOM, 
-based on the project's Kotlin version:
-```kotlin
-plugins {
-    kotlin("jvm") version "2.0.10"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
-}
-
-dependencies {
-    // version 0.3.0 is set by the Gradle plugin
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-core") 
-}
-```
-
 For a full compatibility checklist, 
 see [Versions](https://kotlin.github.io/kotlinx-rpc/versions.html).
 

docs/pages/kotlinx-rpc/help-versions.json

@@ -1,3 +1,3 @@
 [
-  {"version":"0.3.0","url":"/kotlinx-rpc/0.3.0/","isCurrent":true}
+  {"version":"0.4.0","url":"/kotlinx-rpc/0.4.0/","isCurrent":true}
 ]

docs/pages/kotlinx-rpc/rpc.tree

@@ -26,6 +26,7 @@
     </toc-element>
     <toc-element topic="versions.topic"/>
     <toc-element toc-title="Migration guides">
+        <toc-element topic="0-4-0.topic"/>
         <toc-element topic="0-3-0.topic"/>
         <toc-element topic="0-2-4.topic"/>
         <toc-element topic="0-2-1.topic"/>

docs/pages/kotlinx-rpc/topics/0-4-0.topic

@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       title="Migration to 0.4.0" id="0-4-0">
+    <p>
+        Version <code>0.4.0</code> introduces breaking changes.
+    </p>
+    <chapter title="@Rpc Annotation and RemoteService Interface" id="rpc_annotation_and_remote_service_interface">
+        <p>
+            This version brings changes to service definitions.
+            Prior to <code>0.4.0</code> a service was defined as following:
+        </p>
+        <code-block lang="kotlin">
+            interface MyService : RPC
+        </code-block>
+        <p>
+            Starting from <code>0.4.0</code> new service definition is required:
+        </p>
+        <code-block lang="kotlin">
+            @Rpc
+            interface MyService
+        </code-block>
+        <p>
+            This definition will be enough for the project to build, but it is not sufficient for use in IDE.
+            All interfaces annotated with <code>@Rpc</code> are inherently <code>RemoteService</code>.
+            This supertype is added by our compiler plugin.
+            However, IDE can't resolve it yet, so for the code to be highlighted properly,
+            explicit typing is required:
+        </p>
+        <code-block lang="kotlin">
+            @Rpc
+            interface MyService : RemoteService
+        </code-block>
+        <note>
+            The reasoning behind this change is that Kotlin Compiler Plugin API has changed.
+            Versions <code>2.0.0</code> and <code>2.0.10</code> allowed our plugin to resolve marker interfaces (which <code>RPC</code> was)
+            before the code generation phase. Starting from <code>2.0.20</code> this doesn't work,
+            and we are forced to use annotations to reliably detect RPC services.
+            To track changes in this regard, we created an <a href="https://youtrack.jetbrains.com/issue/KT-72654">issue</a> for the compiler team.
+            This change is not the final API design decision, and it may be changed before the stable release.
+        </note>
+    </chapter>
+    <chapter title="Removal of Kotlin versions prior to 2.0" id="removal_of_kotlin_versions_prior_to_2_0">
+        <p>
+            We stopped publishing compiler plugin artifacts for Kotlin versions prior to 2.0.
+            The reason for this is high maintenance cost with little to no usage.
+            We encourage the migration to Kotlin 2.0, where all stable versions are now supported.
+            <br/>
+            List of Kotlin versions that are currently supported: <code>2.0.0</code>, <code>2.0.10</code>, <code>2.0.20</code>, <code>2.0.21</code>
+        </p>
+    </chapter>
+    <chapter title="Removal of org.jetbrains.kotlinx.rpc.platform Gradle plugin"
+             id="removal_of_org_jetbrains_kotlinx_rpc_platform_gradle_plugin">
+        <p>
+            Gradle plugin with id <code>org.jetbrains.kotlinx.rpc.platform</code> is not being published anymore.
+            The reason is that it's sole role was to set BOM in the project, which is now considered unnecessary.
+            <a href="https://docs.gradle.org/current/userguide/platforms.html#sub:conventional-dependencies-toml">Gradle version catalogs</a>
+            can be used instead.
+        </p>
+    </chapter>
+    <chapter title="Removal of BOM from the Gradle plugin" id="removal_of_bom_from_the_gradle_plugin">
+        <p>
+            The Gradle plugin that is left (<code>org.jetbrains.kotlinx.rpc.plugin</code>)
+            does not set BOM for the project anymore. Instead, manual dependency can be set:
+        </p>
+        <code-block lang="kotlin">
+            dependencies {
+                implementation(platform("org.jetbrains.kotlinx:kotlinx-rpc-bom:%kotlinx-rpc-version%"))
+            }
+        </code-block>
+    </chapter>
+</topic>

docs/pages/kotlinx-rpc/topics/features.topic

@@ -36,7 +36,8 @@
                 that will provide your flows with their lifetime:</p>
 
             <code-block lang="kotlin">
-                interface MyService {
+                @Rpc
+                interface MyService : RemoteService {
                     suspend fun sendFlow(flow: Flow&lt;Int&gt;)
                 }
 
@@ -81,6 +82,16 @@
                 }
             </code-block>
             <p>Note that this API is experimental and may be removed in future releases.</p>
+            <p>
+                Another way of managing streams - is to do it manually.
+                For this, <code>StreamScope</code> constructor function can be used on pair with <code>withStreamScope</code>:
+            </p>
+            <code-block lang="kotlin">
+                val streamScope = StreamScope(myJob)
+                withStreamScope(streamScope) {
+                    // use streams here
+                }
+            </code-block>
         </chapter>
     <chapter title="Service fields" id="service-fields">
             <p>Our protocol provides you with an ability to declare service fields:</p>

docs/pages/kotlinx-rpc/topics/get-started.topic

@@ -110,33 +110,23 @@
         </chapter>
 
         <chapter title="Add plugin dependencies" id="add-gradle-plugin">
-            <p><code>kotlinx.rpc</code> provides <a href="plugins.topic">two Gradle plugins</a>:</p>
-            <list>
-                <li>
-                    <a href="plugins.topic" anchor="rpc-platform">
-                        <code>org.jetbrains.kotlinx.rpc.platform</code>
-                    </a>
-                </li>
-                <li>
-                    <a href="plugins.topic" anchor="rpc-plugin">
-                        <code>org.jetbrains.kotlinx.rpc.plugin</code>
-                    </a>
-                </li>
-            </list>
             <p>
-                To add a plugin to your project, you need to define the following in your <path>build.gradle.kts</path>:
+                To add a <a href="plugins.topic">Gradle plugin</a> to your project, you need to define the following in your <path>build.gradle.kts</path>:
             </p>
 
             <code-block lang="kotlin">
                 plugins {
                     id(&quot;org.jetbrains.kotlinx.rpc.plugin&quot;) version &quot;%kotlinx-rpc-version%&quot;
                 }
             </code-block>
-            <p>To learn more about versioning, see <a href="versions.topic"/>.</p>
+
+            <p>
+                This will configure code generation for your project.
+            </p>
         </chapter>
 
         <chapter title="Add serialization dependency" id="add-serialization-dependency">
-            <p><code>kotlinx.rpc</code> requires you to add
+            <p><code>kotlinx.rpc</code> requires you to add the
                 <a href="https://github.com/Kotlin/kotlinx.serialization">kotlinx.serialization</a>
                 Gradle plugin to your project.</p>
 

docs/pages/kotlinx-rpc/topics/plugins.topic

@@ -9,98 +9,24 @@
        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
        title="Plugins" id="plugins">
     <p>
-        The <code>kotlinx.rpc</code> library offers plugins that simplify project configuration by automating repetitive
-        tasks.
-        Specifically, <code>kotlinx.rpc</code> provides two Gradle <a
-            href="https://docs.gradle.org/current/userguide/plugins.html">plugins</a>:
+        The <code>kotlinx.rpc</code> library offers a <a href="https://docs.gradle.org/current/userguide/plugins.html">Gradle plugin</a>
+        that simplifies project configuration by automating repetitive tasks: `org.jetbrains.kotlinx.rpc.plugin`
     </p>
-    <list>
-        <li>
-            <a anchor="rpc-platform">
-                <code>org.jetbrains.kotlinx.rpc.platform</code>
-            </a>
-        </li>
-        <li>
-            <a anchor="rpc-plugin">
-                <code>org.jetbrains.kotlinx.rpc.plugin</code>
-            </a>
-        </li>
-    </list>
 
-    <chapter title="org.jetbrains.kotlinx.rpc.platform" id="rpc-platform">
-        <p>The <code>org.jetbrains.kotlinx.rpc.platform</code> plugin
-            is particularly useful for versioning project dependencies.
-            It adds <a href="https://docs.gradle.org/current/userguide/platforms.html#sub:bom_import">BOM</a>
-            dependency to your project, that specifies proper versions for <code>kotlinx.rpc</code> dependencies.
-            With this, you can skip specifying versions for each runtime dependency:</p>
-
-        <code-block lang="kotlin">
-            plugins {
-                kotlin("jvm") version "%kotlin-version%"
-                id("org.jetbrains.kotlinx.rpc.platform") version "%kotlinx-rpc-version%"
-            }
-
-            dependencies {
-                // versions are set automatically to %kotlinx-rpc-version%
-                implementation(&quot;org.jetbrains.kotlinx:kotlinx-rpc-krpc-client&quot;)
-                implementation(&quot;org.jetbrains.kotlinx:kotlinx-rpc-krpc-server&quot;)
-            }
-        </code-block>
-        <p>Using this plugin with version catalogs, your code can be rewritten like this:</p>
-
-        <code-block lang="yaml">
-            # gradle / libs.versions.toml
-            [versions]
-            kotlinx-rpc-core = "%kotlinx-rpc-version%";
-
-            [libraries]
-            kotlinx-rpc-client = { module = "org.jetbrains.kotlinx:kotlinx-rpc-krpc-client" }
-
-            [plugins]
-            kotlinx-rpc-platform = { id = "org.jetbrains.kotlinx.rpc.platform"; version.ref = "kotlinx-rpc-core"; }
-        </code-block>
-
-        <code-block lang="kotlin">
-            // build.gradle.kts
-            plugins {
-                alias(libs.plugins.kotlinx.rpc.platform)
-            }
-
-            dependencies {
-                implementation(libs.kotlinx.rpc.client)
-            }
-        </code-block>
-    </chapter>
     <chapter title="org.jetbrains.kotlinx.rpc.plugin" id="rpc-plugin">
         <p>
-            The <code>org.jetbrains.kotlinx.rpc.plugin</code> plugin
-            has the same BOM functionality as <a anchor="rpc-platform"><code>org.jetbrains.kotlinx.rpc.platform</code></a> and it also sets
-            up code generation configurations.
+            The <code>org.jetbrains.kotlinx.rpc.plugin</code> plugin sets up code generation configurations.
         </p>
-        <p>It is useful for multi-project setups
-            where you define your <a href="services.topic">RPC services</a> in one set of subprojects and use in the
-            other. In such a setup, you can add the plugin only to modules with service definitions
-            to save time on building your project.</p>
-
         <code-block lang="kotlin">
             plugins {
                 kotlin("jvm") version "%kotlin-version%"
                 id("org.jetbrains.kotlinx.rpc.plugin") version "%kotlinx-rpc-version%"
             }
         </code-block>
-
-        <chapter title="Kotlin versions earlier than 2.0" id="pre-kotlin-2-0">
-            <p>
-                If you are using a version of Kotlin prior to 2.0,
-                you must also add the KSP (Kotlin Symbol Processing) Gradle plugin:
-            </p>
-            <code-block lang="kotlin">
-                plugins {
-                    kotlin("jvm") version "1.9.25"
-                    id("org.jetbrains.kotlinx.rpc.plugin") version "%kotlinx-rpc-version%"
-                    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
-                }
-            </code-block>
-        </chapter>
+        <p>
+            For multi-project setups
+            where you define your <a href="services.topic">RPC services</a> in one set of subprojects and use them in
+            another, you can add the plugin only to modules with service definitions.
+        </p>
     </chapter>
-</topic>
+</topic>

docs/pages/kotlinx-rpc/topics/services.topic

@@ -9,9 +9,12 @@
        xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
        title="Services" id="services">
     <p>Services are the centerpieces of the library.
-                A service is an interface annotated with the <code>RPC</code> annotation,
+                A service is an interface annotated with the <code>@Rpc</code> annotation,
                 and contains a set of methods and fields
                 that can be executed or accessed remotely.
+                Additionally, a service always has a type of <code>RemoteService</code>,
+                which can be specified explicitly, or assumed implicitly and added by a compiler
+                (the latter option does not work in IDE right now, but WIP).
                 A simple service can be declared as follows:</p>
 
             <code-block lang="kotlin">