Skip to content

Commit 5a4a32b

Browse files
Mr3zeeMr3zee
committed
Docs for 0.6.0
1 parent 1f68443 commit 5a4a32b

File tree

9 files changed

+134
-71
lines changed

9 files changed

+134
-71
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.5.1'
23+
CONFIG_JSON_VERSION: '0.6.0'
2424

2525
jobs:
2626
build:

‎README.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ Example of a setup in a project's `build.gradle.kts`:
116116
plugins {
117117
kotlin("multiplatform") version "2.1.20"
118118
kotlin("plugin.serialization") version "2.1.20"
119-
id("org.jetbrains.kotlinx.rpc.plugin") version "0.5.1"
119+
id("org.jetbrains.kotlinx.rpc.plugin") version "0.6.0"
120120
}
121121
```
122122

@@ -131,15 +131,15 @@ And now you can add dependencies to your project:
131131
```kotlin
132132
dependencies {
133133
// Client API
134-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.5.1")
134+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.6.0")
135135
// Server API
136-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.5.1")
136+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.6.0")
137137
// Serialization module. Also, protobuf and cbor are provided
138-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.5.1")
138+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.6.0")
139139

140140
// Transport implementation for Ktor
141-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.5.1")
142-
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.5.1")
141+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.6.0")
142+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.6.0")
143143

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

‎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.5.1","url":"/kotlinx-rpc/0.5.1/","isCurrent":true}
2+
{"version":"0.6.0","url":"/kotlinx-rpc/0.6.0/","isCurrent":true}
33
]

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
3-
- Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
3+
- Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
44
-->
55

66
<!DOCTYPE instance-profile
@@ -36,10 +36,11 @@
3636
<toc-element topic="strict-mode.topic"/>
3737
<toc-element topic="versions.topic"/>
3838
<toc-element toc-title="Migration guides">
39+
<toc-element topic="0-6-0.topic"/>
3940
<toc-element topic="0-5-0.topic"/>
4041
<toc-element topic="0-4-0.topic"/>
4142
<toc-element topic="0-3-0.topic"/>
4243
<toc-element topic="0-2-4.topic"/>
4344
<toc-element topic="0-2-1.topic"/>
4445
</toc-element>
45-
</instance-profile>
46+
</instance-profile>

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
- Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
4+
-->
5+
6+
<!DOCTYPE topic
7+
SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
8+
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
9+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
10+
title="Migration to 0.6.0" id="0-6-0">
11+
12+
<p>
13+
Version <code>0.6.0</code> introduces non-breaking changes, that require migration.
14+
</p>
15+
16+
<chapter title="Non-suspending flows" id="non-suspending-flows">
17+
<p>
18+
Non-suspending server flows are now supported.
19+
That begins the deprecation cycle for the suspending server flows and stream scopes.
20+
Please refer to the <a href="strict-mode.topic"/> section for more details on the migration
21+
(sections <code>Non-suspending server flows</code> and <code>Stream scopes management</code>).
22+
</p>
23+
</chapter>
24+
</topic>

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

Lines changed: 5 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
3-
- Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
3+
- Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
44
-->
55

66
<!DOCTYPE topic
@@ -25,15 +25,15 @@
2525

2626
@Rpc
2727
interface MyService : RemoteService {
28-
suspend fun sendStream(stream: Flow&lt;Int&gt;): Flow&lt;String&gt;
28+
fun sendStream(stream: Flow&lt;Int&gt;): Flow&lt;String&gt;
2929

3030
suspend fun streamRequest(request: StreamRequest)
3131
}
3232
</code-block>
3333

3434
<p>
3535
Another requirement is that server-side steaming (flows that are returned from a function),
36-
must be the top-level type:
36+
must be the top-level type and the function must be non-suspending:
3737
</p>
3838

3939
<code-block lang="kotlin">
@@ -45,7 +45,8 @@
4545

4646
@Rpc
4747
interface MyService : RemoteService {
48-
suspend fun serverStream(): Flow&lt;String&gt; // ok
48+
fun serverStream(): Flow&lt;String&gt; // ok
49+
suspend fun serverStream(): Flow&lt;String&gt; // not ok
4950
suspend fun serverStream(): StreamResult // not ok
5051
}
5152
</code-block>
@@ -55,57 +56,5 @@
5556
<a href="https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md#contextual-serialization">Contextual</a>
5657
annotation.
5758
</note>
58-
59-
<p>
60-
To use flows in your code, use the <code>streamScoped</code> function
61-
that will provide your flows with their lifetime:
62-
</p>
63-
64-
<code-block lang="kotlin">
65-
@Rpc
66-
interface MyService : RemoteService {
67-
suspend fun sendFlow(flow: Flow&lt;Int&gt;)
68-
}
69-
70-
val myService = rpcClient.withService&lt;MyService&gt;()
71-
72-
streamScoped {
73-
val flow = flow {
74-
repeat(10) { i -&gt;
75-
emit(i)
76-
}
77-
}
78-
79-
myService.sendFlow(flow)
80-
}
81-
</code-block>
82-
<p>
83-
In that case all your flows, including incoming and outgoing,
84-
will work until the <code>streamScoped</code> function completes.
85-
After that, all streams that are still live will be closed.
86-
</p>
87-
<p>
88-
You can have multiple RPC calls and flows inside the <code>streamScoped</code> function, including those from
89-
different services.
90-
</p>
91-
<p>
92-
On the server side, you can use the <code>invokeOnStreamScopeCompletion</code> handler inside your methods
93-
to execute code after <code>streamScoped</code> on the client side has closed.
94-
It might be useful to clean resources, for example.
95-
</p>
96-
<warning>
97-
Note that this API is experimental and may be removed in future releases.
98-
</warning>
99-
<p>
100-
Another way of managing streams is to do it manually.
101-
For this, you can use the <code>StreamScope</code> constructor function together with
102-
<code>withStreamScope</code>:
103-
</p>
104-
<code-block lang="kotlin">
105-
val streamScope = StreamScope(myJob)
106-
withStreamScope(streamScope) {
107-
// use streams here
108-
}
109-
</code-block>
11059
</chapter>
11160
</topic>

‎docs/pages/kotlinx-rpc/topics/strict-mode.topic‎

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
- Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
4+
-->
5+
26
<!DOCTYPE topic
37
SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
48
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -63,6 +67,89 @@
6367
}
6468
</code-block>
6569
</li>
70+
<li>
71+
<b>Non-suspending server flows</b>
72+
<p>Deprecation level: <code>WARNING</code></p>
73+
74+
<code-block lang="kotlin">
75+
data class SpotifyWrapped(val extra: Data)
76+
77+
@Rpc
78+
interface Service : RemoteService {
79+
suspend fun old(): Flow&lt;SpotifyWrapped&gt; // deprecated
80+
81+
fun new(): Flow&lt;SpotifyWrapped&gt;
82+
}
83+
</code-block>
84+
</li>
85+
<li>
86+
<b>Stream scopes management</b>
87+
<p>Deprecation level: <code>WARNING</code></p>
88+
89+
<p>
90+
The next stream scope management structures are deprecated due to the introduction of
91+
non-suspending server flows:
92+
</p>
93+
<list>
94+
<li><code>StreamScoped</code> class and function</li>
95+
<li><code>streamScoped</code> function</li>
96+
<li><code>invokeOnStreamScopeCompletion</code> function</li>
97+
<li><code>withStreamScope</code> function</li>
98+
</list>
99+
<p>
100+
Stream collection and completion is now bound to the <code>CoroutineScope</code> in which the flow was
101+
collected (server-side flows) or produced (client-side flows).
102+
</p>
103+
<p>
104+
Old code:
105+
</p>
106+
<code-block lang="kotlin">
107+
@Rpc
108+
interface Service : RemoteService {
109+
suspend fun oldClient(flow: Flow&lt;Int&gt;)
110+
suspend fun oldServer(): Flow&lt;Int&gt;
111+
}
112+
113+
suspend fun consumer(service: Service) {
114+
streamScoped {
115+
service.oldClient(flow { /* ... */ } )
116+
117+
service.oldServer().collect {
118+
// ...
119+
}
120+
}
121+
}
122+
</code-block>
123+
<p>
124+
New code:
125+
</p>
126+
<code-block lang="kotlin">
127+
@Rpc
128+
interface Service : RemoteService {
129+
suspend fun newClient(flow: Flow&lt;Int&gt;)
130+
fun newServer(): Flow&lt;Int&gt;
131+
}
132+
133+
fun consumer(service: Service, scope: CoroutineScope) {
134+
val flow = service.new()
135+
scope.launch {
136+
service.newClient(flow { /* ... */ } )
137+
138+
flow.collect {
139+
// ...
140+
}
141+
}
142+
}
143+
// or
144+
suspend fun consumer(service: Service) {
145+
service.newClient(flow { /* ... */ } )
146+
147+
service.new().collect {
148+
// ...
149+
}
150+
}
151+
</code-block>
152+
</li>
66153
</list>
67154

68155
<p>
@@ -81,6 +168,8 @@
81168
nestedFlow = RpcStrictMode.WARNING
82169
notTopLevelServerFlow = RpcStrictMode.WARNING
83170
fields = RpcStrictMode.WARNING
171+
suspendingServerStreaming = RpcStrictMode.WARNING
172+
streamScopedFunctions = RpcStrictMode.WARNING
84173
}
85174
}
86175
</code-block>
@@ -90,7 +179,7 @@
90179

91180
<warning>
92181
Note that setting <code>RpcStrictMode.NONE</code> should not be done permanently.
93-
All deprecated APIs will become errors in future without an option to suppress it.
182+
All deprecated APIs will become errors in the future without an option to suppress them.
94183
Consider your migration path in advance.
95184
</warning>
96185
</topic>

‎docs/pages/kotlinx-rpc/v.list‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
3-
- Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
3+
- Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
44
-->
55

66
<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/writerside/1.0/vars.dtd">
@@ -14,6 +14,6 @@
1414
<var name="host" value="https://kotlin.github.io"/>
1515

1616
<!-- Library versions -->
17-
<var name="kotlinx-rpc-version" value="0.5.1"/>
17+
<var name="kotlinx-rpc-version" value="0.6.0"/>
1818
<var name="kotlin-version" value="2.1.20"/>
1919
</vars>

‎docs/pages/kotlinx-rpc/writerside.cfg‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?xml version="1.0" encoding="UTF-8"?>
22
<!--
3-
- Copyright 2023-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
3+
- Copyright 2023-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
44
-->
55

66
<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">
@@ -12,5 +12,5 @@
1212
<images dir="images" web-path="images/"/>
1313
<categories src="c.list"/>
1414
<vars src="v.list"/>
15-
<instance src="rpc.tree" version="0.5.1" web-path="/kotlinx-rpc/"/>
15+
<instance src="rpc.tree" version="0.6.0" web-path="/kotlinx-rpc/"/>
1616
</ihp>

0 commit comments

Comments
 (0)