Skip to content

Commit ca570f1

Browse files
Mr3zeeMr3zee
committed
Updated docs for the 0.5.0 release
1 parent 7a2c065 commit ca570f1

15 files changed

+493
-172
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ env:
2020
ALGOLIA_INDEX_NAME: 'prod_kotlin_rpc'
2121
ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}'
2222
CONFIG_JSON_PRODUCT: 'kotlinx-rpc'
23-
CONFIG_JSON_VERSION: '0.4.0'
23+
CONFIG_JSON_VERSION: '0.5.0'
2424

2525
jobs:
2626
build:

‎README.md‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,23 +25,36 @@ import kotlinx.rpc.annotations.Rpc
2525
@Rpc
2626
interface AwesomeService : RemoteService {
2727
suspend fun getNews(city: String): Flow<String>
28+
29+
suspend fun daysUntilStableRelese(): Int
2830
}
2931
```
3032
In your server code define how to respond by simply implementing the service:
3133
```kotlin
32-
class AwesomeServiceImpl(override val coroutineContext: CoroutineContext) : AwesomeService {
34+
class AwesomeServiceImpl(
35+
val parameters: AwesomeParameters,
36+
override val coroutineContext: CoroutineContext,
37+
) : AwesomeService {
3338
override suspend fun getNews(city: String): Flow<String> {
3439
return flow {
3540
emit("Today is 23 degrees!")
3641
emit("Harry Potter is in $city!")
3742
emit("New dogs cafe has opened doors to all fluffy customers!")
3843
}
3944
}
45+
46+
override suspend fun daysUntilStableRelese(): Int {
47+
retuen if (parameters.stable) 0 else {
48+
parameters.daysUntilStable ?: error("Who says it will be stable?")
49+
}
50+
}
4051
}
4152
```
4253
Then, choose how do you want your service to communicate. For example, you can use integration with [Ktor](https://ktor.io/):
4354

4455
```kotlin
56+
data class AwesomeParameters(val stable: Boolean, val daysUntilStable: Int?)
57+
4558
fun main() {
4659
embeddedServer(Netty, 8080) {
4760
install(Krpc)
@@ -53,7 +66,9 @@ fun main() {
5366
}
5467
}
5568

56-
registerService<AwesomeService> { ctx -> AwesomeServiceImpl(ctx) }
69+
registerService<AwesomeService> { ctx ->
70+
AwesomeServiceImpl(AwesomeParameters(false, null), ctx)
71+
}
5772
}
5873
}
5974
}.start(wait = true)
@@ -71,8 +86,12 @@ val rpcClient = HttpClient { installKrpc() }.rpc {
7186
}
7287
}
7388

89+
val service = rpcClient.withService<AwesomeService>()
90+
91+
service.daysUntilStableRelese()
92+
7493
streamScoped {
75-
rpcClient.withService<AwesomeService>().getNews("KotlinBurg").collect { article ->
94+
service.getNews("KotlinBurg").collect { article ->
7695
println(article)
7796
}
7897
}
@@ -92,7 +111,7 @@ Example of a setup in a project's `build.gradle.kts`:
92111
plugins {
93112
kotlin("multiplatform") version "2.1.0"
94113
kotlin("plugin.serialization") version "2.1.0"
95-
id("org.jetbrains.kotlinx.rpc.plugin") version "0.4.0"
114+
id("org.jetbrains.kotlinx.rpc.plugin") version "0.5.0"
96115
}
97116
```
98117

@@ -107,15 +126,15 @@ And now you can add dependencies to your project:
107126
```kotlin
108127
dependencies {
109128
// Client API
110-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.4.0")
129+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.5.0")
111130
// Server API
112-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.4.0")
131+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.5.0")
113132
// Serialization module. Also, protobuf and cbor are provided
114-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.4.0")
133+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.5.0")
115134

116135
// Transport implementation for Ktor
117-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.4.0")
118-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.4.0")
136+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.5.0")
137+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.5.0")
119138

120139
// Ktor API
121140
implementation("io.ktor:ktor-client-cio-jvm:$ktor_version")

‎docs/pages/kotlinx-rpc/.idea/kotlinx-rpc.iml‎

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/pages/kotlinx-rpc/.idea/modules.xml‎

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
[
2-
{"version":"0.4.0","url":"/kotlinx-rpc/0.4.0/","isCurrent":true}
2+
{"version":"0.5.0","url":"/kotlinx-rpc/0.5.0/","isCurrent":true}
33
]

‎docs/pages/kotlinx-rpc/rpc.tree‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,10 @@
1414
<toc-element topic="plugins.topic"/>
1515
<toc-element toc-title="Core concepts">
1616
<toc-element topic="services.topic"/>
17+
<toc-element topic="service-descriptors.topic"/>
1718
<toc-element topic="rpc-clients.topic"/>
1819
<toc-element topic="rpc-servers.topic"/>
20+
<toc-element topic="annotation-type-safety.topic"/>
1921
</toc-element>
2022
<toc-element toc-title="Protocols">
2123
<toc-element toc-title="kRPC">
@@ -24,8 +26,10 @@
2426
<toc-element topic="transport.topic"/>
2527
</toc-element>
2628
</toc-element>
29+
<toc-element topic="strict-mode.topic"/>
2730
<toc-element topic="versions.topic"/>
2831
<toc-element toc-title="Migration guides">
32+
<toc-element topic="0-5-0.topic"/>
2933
<toc-element topic="0-4-0.topic"/>
3034
<toc-element topic="0-3-0.topic"/>
3135
<toc-element topic="0-2-4.topic"/>

‎docs/pages/kotlinx-rpc/topics/0-5-0.topic‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE topic
3+
SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
4+
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
6+
title="Migration to 0.5.0" id="0-5-0">
7+
8+
<p>
9+
Version <code>0.5.0</code> introduces breaking changes.
10+
</p>
11+
12+
<chapter title="Annotation type-safety" id="annotation-type-safety">
13+
<p>
14+
This release brings <a href="annotation-type-safety.topic">annotation type-safety</a>.
15+
This means that some green code technically can become red:
16+
</p>
17+
<code-block lang="Kotlin">
18+
@Rpc
19+
interface MyService : RemoteService
20+
21+
class MyServiceImpl : MyService
22+
23+
fun &lt;@Rpc T : Any&gt; withService() {}
24+
</code-block>
25+
26+
<code-block lang="Kotlin">
27+
withService&lt;MyService&gt;() // ok
28+
withService&lt;MyServiceImpl&gt;() // ok in 0.4.0, error in 0.5.0
29+
</code-block>
30+
<p>
31+
Thar should not be a problem, as this code was wrong in both releases anyway and would fail in runtime in <code>0.4.0</code>.
32+
</p>
33+
</chapter>
34+
35+
<chapter title="Strict Mode and Service API deprecations" id="strict-mode">
36+
<p>
37+
This release introduces <a href="strict-mode.topic">Strict Mode</a>.
38+
Some service declarations are now deprecated, currently with a warning.
39+
In the following releases it will change to an error.
40+
</p>
41+
<p>
42+
Deprecated service APIs:
43+
</p>
44+
<list>
45+
<li><code>StateFlow</code> and <code>SharedFlow</code> usage</li>
46+
<li>Fields in services</li>
47+
<li>Nested Flows</li>
48+
<li>Not top-level server side flows</li>
49+
</list>
50+
<p>
51+
More info on the <a href="strict-mode.topic">Strict Mode page</a>.
52+
</p>
53+
</chapter>
54+
55+
<chapter title="API Renaming" id="api-renaming">
56+
The following APIs were renamed to satisfy Kotlin style guides and bring even more consistency to the library:
57+
<table>
58+
<tr>
59+
<td>Old</td>
60+
<td>New</td>
61+
</tr>
62+
<tr>
63+
<td>kotlinx.rpc.RPCClient</td>
64+
<td>kotlinx.rpc.RpcClient</td>
65+
</tr>
66+
<tr>
67+
<td>kotlinx.rpc.RPCServer</td>
68+
<td>kotlinx.rpc.RpcServer</td>
69+
</tr>
70+
<tr>
71+
<td>kotlinx.rpc.UninitializedRPCFieldException</td>
72+
<td>kotlinx.rpc.UninitializedRpcFieldException</td>
73+
</tr>
74+
<tr>
75+
<td>kotlinx.rpc.RPCEagerField</td>
76+
<td>kotlinx.rpc.RpcEagerField</td>
77+
</tr>
78+
<tr>
79+
<td>kotlinx.rpc.RPCEagerField</td>
80+
<td>kotlinx.rpc.RpcEagerField</td>
81+
</tr>
82+
<tr>
83+
<td>kotlinx.rpc.internal.utils.InternalRPCApi</td>
84+
<td>kotlinx.rpc.internal.utils.InternalRpcApi</td>
85+
</tr>
86+
<tr>
87+
<td>kotlinx.rpc.internal.utils.ExperimentalRPCApi</td>
88+
<td>kotlinx.rpc.internal.utils.ExperimentalRpcApi</td>
89+
</tr>
90+
<tr>
91+
<td>kotlinx.rpc.krpc.RPCConfig</td>
92+
<td>kotlinx.rpc.krpc.KrpcConfig</td>
93+
</tr>
94+
<tr>
95+
<td>kotlinx.rpc.krpc.RPCConfigBuilder</td>
96+
<td>kotlinx.rpc.krpc.KrpcConfigBuilder</td>
97+
</tr>
98+
<tr>
99+
<td>kotlinx.rpc.krpc.RPCTransport</td>
100+
<td>kotlinx.rpc.krpc.KrpcTransport</td>
101+
</tr>
102+
<tr>
103+
<td>kotlinx.rpc.krpc.RPCTransportMessage</td>
104+
<td>kotlinx.rpc.krpc.KrpcTransportMessage</td>
105+
</tr>
106+
<tr>
107+
<td>kotlinx.rpc.krpc.client.KRPCClient</td>
108+
<td>kotlinx.rpc.krpc.client.KrpcClient</td>
109+
</tr>
110+
<tr>
111+
<td>kotlinx.rpc.krpc.server.KRPCServer</td>
112+
<td>kotlinx.rpc.krpc.server.KrpcServer</td>
113+
</tr>
114+
<tr>
115+
<td>kotlinx.rpc.krpc.ktor.client.installRPC</td>
116+
<td>kotlinx.rpc.krpc.ktor.client.installKrpc</td>
117+
</tr>
118+
<tr>
119+
<td>kotlinx.rpc.krpc.ktor.client.RPC</td>
120+
<td>kotlinx.rpc.krpc.ktor.client.Krpc</td>
121+
</tr>
122+
<tr>
123+
<td>kotlinx.rpc.krpc.ktor.client.KtorRPCClient</td>
124+
<td>kotlinx.rpc.krpc.ktor.client.KtorRpcClient</td>
125+
</tr>
126+
<tr>
127+
<td>kotlinx.rpc.krpc.ktor.server.RPC</td>
128+
<td>kotlinx.rpc.krpc.ktor.server.Krpc</td>
129+
</tr>
130+
<tr>
131+
<td>kotlinx.rpc.krpc.ktor.server.RPCRoute</td>
132+
<td>kotlinx.rpc.krpc.ktor.server.KrpcRoute</td>
133+
</tr>
134+
<tr>
135+
<td>kotlinx.rpc.krpc.serialization.RPCSerialFormat</td>
136+
<td>kotlinx.rpc.krpc.serialization.KrpcSerialFormat</td>
137+
</tr>
138+
<tr>
139+
<td>kotlinx.rpc.krpc.serialization.RPCSerialFormatBuilder</td>
140+
<td>kotlinx.rpc.krpc.serialization.KrpcSerialFormatBuilder</td>
141+
</tr>
142+
<tr>
143+
<td>kotlinx.rpc.krpc.serialization.RPCSerialFormatConfiguration</td>
144+
<td>kotlinx.rpc.krpc.serialization.KrpcSerialFormatConfiguration</td>
145+
</tr>
146+
<tr>
147+
<td>kotlinx.rpc.krpc.serialization.cbor.RPCCborSerialFormat</td>
148+
<td>kotlinx.rpc.krpc.serialization.cbor.KrpcCborSerialFormat</td>
149+
</tr>
150+
<tr>
151+
<td>kotlinx.rpc.krpc.serialization.json.RPCJsonSerialFormat</td>
152+
<td>kotlinx.rpc.krpc.serialization.json.KrpcJsonSerialFormat</td>
153+
</tr>
154+
<tr>
155+
<td>kotlinx.rpc.krpc.serialization.protobuf.RPCProtobufSerialFormat</td>
156+
<td>kotlinx.rpc.krpc.serialization.protobuf.KrpcProtobufSerialFormat</td>
157+
</tr>
158+
</table>
159+
</chapter>
160+
161+
<chapter title="Service Descriptors" id="service-descriptors">
162+
<p>
163+
New API is introduced to access compiler generated code - <a href="service-descriptors.topic"/>.
164+
</p>
165+
</chapter>
166+
</topic>

‎docs/pages/kotlinx-rpc/topics/annotation-type-safety.topic‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE topic
3+
SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
4+
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
6+
title="Annotation type-safety" id="annotation-type-safety">
7+
8+
<p>
9+
Library introduces a concept of annotation type-safety. Consider the following example:
10+
</p>
11+
<code-block lang="Kotlin">
12+
@Rpc
13+
interface MyService : RemoteService
14+
15+
class MyServiceImpl : MyService
16+
17+
fun &lt;T : RemoteService&gt; withService() {}
18+
</code-block>
19+
<p>
20+
Compiler can not guarantee, that the passed type is the one for which the code generation was run:
21+
</p>
22+
<code-block lang="Kotlin">
23+
withService&lt;MyService&gt;() // ok
24+
withService&lt;MyServiceImpl&gt;() // compile time ok, runtime throws
25+
</code-block>
26+
<p>
27+
Our compiler plugin, however, can make this code behave as expected.
28+
</p>
29+
<code-block lang="Kotlin">
30+
@Rpc
31+
interface MyService : RemoteService
32+
33+
class MyServiceImpl : MyService
34+
35+
fun &lt;@Rpc T : Any&gt; withService() {}
36+
</code-block>
37+
38+
<code-block lang="Kotlin">
39+
withService&lt;MyService&gt;() // ok
40+
withService&lt;MyServiceImpl&gt;() // compile time error
41+
</code-block>
42+
43+
<note>
44+
Annotation type safety only ensures that the resolved type parameters are annotated with the required annotation.
45+
The actual type of the passed argument may differ:
46+
<code-block lang="Kotlin">
47+
fun &lt;@Rpc T : Any&gt; registerService(body: () -> T) {}
48+
49+
// ok, T is resolved to MyService,
50+
// but 'body' parameter returns MyServiceImpl
51+
registerService&lt;MyService&gt; { ctx -> MyServiceImpl(ctx) }
52+
53+
// error, T is resolved to MyServiceImpl
54+
registerService { ctx -> MyServiceImpl(ctx) }
55+
</code-block>
56+
</note>
57+
58+
<warning>
59+
The feature is highly experimental.
60+
The concept will stay, however due to the complexity of the implementation,
61+
our compiler plugin may behave unexpectedly when performing type-safety checks.
62+
Please, <a href="https://github.com/Kotlin/kotlinx-rpc/issues/new?template=bug_report.md">report</a> any encountered bugs.
63+
64+
To ensure critical bugs don't paralyze your app, there is a kill-switch present for the feature:
65+
<code-block lang="Kotlin">
66+
// build.gradle.kts
67+
rpc {
68+
annotationTypeSafetyEnabled = false // true by default
69+
}
70+
</code-block>
71+
</warning>
72+
</topic>

‎docs/pages/kotlinx-rpc/topics/configuration.topic‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@
5353
<code>sharedFlowParameters</code> DSL
5454
</title>
5555

56+
<warning>
57+
These parameters are deprecated since <code>0.5.0</code>, see the <a href="0-5-0.topic">migration guide</a>.
58+
</warning>
59+
5660
<code-block lang="kotlin">
5761
rpcClientConfig {
5862
sharedFlowParameters {

0 commit comments

Comments
 (0)