Skip to content

Commit 7cce139

Browse files
Mr3zeeMr3zee
authored
Platforms Table and docs (#356)
1 parent a3e2356 commit 7cce139

File tree

16 files changed

+641
-76
lines changed

16 files changed

+641
-76
lines changed

‎.github/workflows/platforms.yml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Verify Platforms Table
2+
3+
on:
4+
pull_request:
5+
6+
permissions:
7+
contents: read
8+
9+
jobs:
10+
verify-platforms-table:
11+
name: Run Verification
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout Sources
15+
uses: actions/checkout@v4
16+
- name: Setup Gradle
17+
uses: gradle/actions/setup-gradle@v3
18+
- name: Check Platforms Table
19+
run: ./gradlew verifyPlatformTable --no-configuration-cache

‎README.md

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -19,22 +19,16 @@ Build your RPC with already known language constructs and nothing more!
1919

2020
First, create your RPC service and define some methods:
2121
```kotlin
22-
import kotlinx.rpc.RemoteService
23-
import kotlinx.rpc.annotations.Rpc
24-
2522
@Rpc
26-
interface AwesomeService : RemoteService {
23+
interface AwesomeService {
2724
fun getNews(city: String): Flow<String>
2825

2926
suspend fun daysUntilStableRelease(): Int
3027
}
3128
```
3229
In your server code define how to respond by simply implementing the service:
3330
```kotlin
34-
class AwesomeServiceImpl(
35-
val parameters: AwesomeParameters,
36-
override val coroutineContext: CoroutineContext,
37-
) : AwesomeService {
31+
class AwesomeServiceImpl(val parameters: AwesomeParameters) : AwesomeService {
3832
override fun getNews(city: String): Flow<String> {
3933
return flow {
4034
emit("Today is 23 degrees!")
@@ -66,8 +60,8 @@ fun main() {
6660
}
6761
}
6862

69-
registerService<AwesomeService> { ctx ->
70-
AwesomeServiceImpl(AwesomeParameters(false, null), ctx)
63+
registerService<AwesomeService> {
64+
AwesomeServiceImpl(AwesomeParameters(false, null))
7165
}
7266
}
7367
}
@@ -90,10 +84,8 @@ val service = rpcClient.withService<AwesomeService>()
9084

9185
service.daysUntilStableRelease()
9286

93-
streamScoped {
94-
service.getNews("KotlinBurg").collect { article ->
95-
println(article)
96-
}
87+
service.getNews("KotlinBurg").collect { article ->
88+
println(article)
9789
}
9890
```
9991

@@ -106,6 +98,33 @@ Check out our [getting started guide](https://kotlin.github.io/kotlinx-rpc) for
10698
To ensure that all IDE features of our compiler plugin work properly on IntelliJ-based IDEs, install the
10799
[Kotlin External FIR Support](https://plugins.jetbrains.com/plugin/26480-kotlin-external-fir-support?noRedirect=true) plugin.
108100

101+
## Kotlin compatibility
102+
We support all stable Kotlin versions starting from 2.0.0:
103+
- 2.0.0, 2.0.10, 2.0.20, 2.0.21
104+
- 2.1.0, 2.1.10, 2.1.20, 2.1.21
105+
106+
For a full compatibility checklist,
107+
see [Versions](https://kotlin.github.io/kotlinx-rpc/versions.html).
108+
109+
## Supported Platforms
110+
111+
`kotlinx.rpc` is a KMP library, so we aim to support all available platforms.
112+
113+
However, we are also a multi-module library, meaning that some modules may not support some platforms.
114+
115+
Current high-level status:
116+
117+
| Subsystem | Supported Platforms | Notes |
118+
|-----------|--------------------------------------------------|---------------------------------------------------------------------------------------------|
119+
| Core | Jvm, Js, WasmJs, WasmWasi, Apple, Linux, Windows | |
120+
| kRPC | Jvm, Js, WasmJs, Apple, Linux, Windows | WasmWasi is blocked by [kotlin-logging](https://github.com/oshai/kotlin-logging/issues/433) |
121+
| gRPC | Jvm | Projects with `kotlin("jvm")` **only**! <br/> KMP support is in development |
122+
123+
For more detailed module by module information,
124+
check out our [platform support table](https://kotlin.github.io/kotlinx-rpc/platforms.html).
125+
126+
For information about gRPC, see [gRPC Integration](#grpc-integration)
127+
109128
### Gradle plugins
110129

111130
`kotlinx.rpc` provides Gradle plugin `org.jetbrains.kotlinx.rpc.plugin`
@@ -174,14 +193,6 @@ For more information on gRPC usage,
174193
see the [official documentation](https://kotlin.github.io/kotlinx-rpc/grpc-configuration.html).
175194
For a working example, see the [sample gRPC project](/samples/grpc-app).
176195

177-
## Kotlin compatibility
178-
We support all stable Kotlin versions starting from 2.0.0:
179-
- 2.0.0, 2.0.10, 2.0.20, 2.0.21
180-
- 2.1.0, 2.1.10, 2.1.20, 2.1.21
181-
182-
For a full compatibility checklist,
183-
see [Versions](https://kotlin.github.io/kotlinx-rpc/versions.html).
184-
185196
## JetBrains Product
186197

187198
`kotlinx.rpc` is an official [JetBrains](https://jetbrains.com) product and is primarily developed by the team at JetBrains, with

‎build.gradle.kts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ import org.jetbrains.kotlin.gradle.plugin.getKotlinPluginVersion
66
import util.configureApiValidation
77
import util.configureNpm
88
import util.configureProjectReport
9+
import util.registerDumpPlatformTableTask
910
import util.libs
11+
import util.registerVerifyPlatformTableTask
1012

1113
plugins {
1214
alias(libs.plugins.serialization) apply false
@@ -21,6 +23,9 @@ configureProjectReport()
2123
configureNpm()
2224
configureApiValidation()
2325

26+
registerDumpPlatformTableTask()
27+
registerVerifyPlatformTableTask()
28+
2429
val kotlinVersion = rootProject.libs.versions.kotlin.lang.get()
2530
val kotlinCompiler = rootProject.libs.versions.kotlin.compiler.get()
2631

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
</toc-element>
4040
<toc-element topic="strict-mode.topic"/>
4141
<toc-element topic="versions.topic"/>
42+
<toc-element topic="platforms.topic"/>
4243
<toc-element toc-title="Migration guides">
4344
<toc-element topic="0-8-0.topic"/>
4445
<toc-element topic="0-6-0.topic"/>

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,29 @@
222222
</code-block>
223223
</compare>
224224
</li>
225+
<li>
226+
<p>
227+
<code>RpcCall</code> changed parameter name and type for function's data:
228+
</p>
229+
<compare type="top-bottom">
230+
<code-block lang="Kotlin">
231+
class RpcCall(
232+
val descriptor: RpcServiceDescriptor&lt;*&gt;,
233+
val callableName: String,
234+
val data: Any?,
235+
val serviceId: Long,
236+
)
237+
</code-block>
238+
<code-block lang="Kotlin">
239+
class RpcCall(
240+
val descriptor: RpcServiceDescriptor&lt;*&gt;,
241+
val callableName: String,
242+
val parameters: Array&lt;Any?&gt;,
243+
val serviceId: Long,
244+
)
245+
</code-block>
246+
</compare>
247+
</li>
225248
<li>
226249
<p>
227250
For Ktor, <code>HttpClient.rpc</code> extension function is now non-suspendable.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,11 @@
1010
</p>
1111
<code-block lang="Kotlin">
1212
@Rpc
13-
interface MyService : RemoteService
13+
interface MyService
1414

1515
class MyServiceImpl : MyService
1616

17-
fun &lt;T : RemoteService&gt; withService() {}
17+
fun &lt;T&gt; withService() {}
1818
</code-block>
1919
<p>
2020
The compiler can't guarantee that the passed type parameter is the one for which the code generation was run:

‎docs/pages/kotlinx-rpc/topics/krpc-ktor.topic

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@
8787
)
8888

8989
@Rpc
90-
interface ImageService : RemoteService {
90+
interface ImageService {
9191
suspend fun processImage(url: String): ProcessedImage
9292
}
9393
</code-block>

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

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!DOCTYPE topic
3+
SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
4+
<!--suppress WrsMissingSpaceChecker -->
5+
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6+
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
7+
title="Platforms" id="platforms">
8+
9+
10+
<p>
11+
<code>kotlinx.rpc</code> is a KMP library, so we aim to support all available platforms.
12+
13+
However, we are also a multi-module library, meaning that some modules may not support some platforms.
14+
15+
Current high-level status:
16+
</p>
17+
<table>
18+
<tr>
19+
<td>Subsystem</td>
20+
<td>Supported Platforms</td>
21+
<td>Notes</td>
22+
</tr>
23+
<tr>
24+
<td>Core</td>
25+
<td>Jvm, Js, WasmJs, WasmWasi, Apple, Linux, Windows</td>
26+
<td></td>
27+
</tr>
28+
<tr>
29+
<td>kRPC</td>
30+
<td>Jvm, Js, WasmJs, Apple, Linux, Windows</td>
31+
<td>
32+
WasmWasi is blocked by <a href="https://github.com/oshai/kotlin-logging/issues/433">kotlin-logging</a>.
33+
</td>
34+
</tr>
35+
<tr>
36+
<td>gRPC</td>
37+
<td>Jvm</td>
38+
<td>
39+
<p>
40+
Projects with <code>kotlin("jvm")</code> <b>only</b>!
41+
</p>
42+
<p>
43+
KMP support is in development
44+
</p>
45+
</td>
46+
</tr>
47+
</table>
48+
49+
<p>
50+
The following table contains a list of all published modules and their supported platforms:
51+
</p>
52+
<table>
53+
<tr>
54+
<td>Module</td>
55+
<td>Jvm</td>
56+
<td>Js</td>
57+
<td>Wasm</td>
58+
<td>Native</td>
59+
</tr>
60+
<!-- Don't delete comment tags, they are used for automated platforms table generation -->
61+
<!-- Don't modify content in between the tags -->
62+
<!-- PLATFORMS_TABLE_START -->
63+
<tr>
64+
<td>core</td>
65+
<td>jvm</td>
66+
<td><list><li>browser</li><li>node</li></list></td>
67+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li><li>wasmWasi<list><li>node</li></list></li></list></td>
68+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm32</li><li>watchosArm64</li><li>watchosDeviceArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
69+
</tr>
70+
71+
<tr>
72+
<td>utils</td>
73+
<td>jvm</td>
74+
<td><list><li>browser</li><li>node</li></list></td>
75+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li><li>wasmWasi<list><li>node</li></list></li></list></td>
76+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm32</li><li>watchosArm64</li><li>watchosDeviceArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
77+
</tr>
78+
79+
<tr>
80+
<td>krpc-client</td>
81+
<td>jvm</td>
82+
<td><list><li>browser</li><li>node</li></list></td>
83+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
84+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
85+
</tr>
86+
87+
<tr>
88+
<td>krpc-core</td>
89+
<td>jvm</td>
90+
<td><list><li>browser</li><li>node</li></list></td>
91+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
92+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
93+
</tr>
94+
95+
<tr>
96+
<td>krpc-logging</td>
97+
<td>jvm</td>
98+
<td><list><li>browser</li><li>node</li></list></td>
99+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
100+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
101+
</tr>
102+
103+
<tr>
104+
<td>krpc-server</td>
105+
<td>jvm</td>
106+
<td><list><li>browser</li><li>node</li></list></td>
107+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
108+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
109+
</tr>
110+
111+
<tr>
112+
<td>krpc-test</td>
113+
<td>jvm</td>
114+
<td><list><li>browser</li><li>node</li></list></td>
115+
<td><list><li>wasmJs<list><li>browser</li><li>node</li></list></li></list></td>
116+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
117+
</tr>
118+
119+
<tr>
120+
<td>krpc-ktor-client</td>
121+
<td>jvm</td>
122+
<td><list><li>browser</li><li>node</li></list></td>
123+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
124+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
125+
</tr>
126+
127+
<tr>
128+
<td>krpc-ktor-core</td>
129+
<td>jvm</td>
130+
<td><list><li>browser</li><li>node</li></list></td>
131+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
132+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
133+
</tr>
134+
135+
<tr>
136+
<td>krpc-ktor-server</td>
137+
<td>jvm</td>
138+
<td><list><li>browser</li><li>node</li></list></td>
139+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
140+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
141+
</tr>
142+
143+
<tr>
144+
<td>krpc-serialization-cbor</td>
145+
<td>jvm</td>
146+
<td><list><li>browser</li><li>node</li></list></td>
147+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
148+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
149+
</tr>
150+
151+
<tr>
152+
<td>krpc-serialization-core</td>
153+
<td>jvm</td>
154+
<td><list><li>browser</li><li>node</li></list></td>
155+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
156+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
157+
</tr>
158+
159+
<tr>
160+
<td>krpc-serialization-json</td>
161+
<td>jvm</td>
162+
<td><list><li>browser</li><li>node</li></list></td>
163+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
164+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
165+
</tr>
166+
167+
<tr>
168+
<td>krpc-serialization-protobuf</td>
169+
<td>jvm</td>
170+
<td><list><li>browser</li><li>node</li></list></td>
171+
<td><list><li>wasmJs<list><li>browser</li><li>d8</li><li>node</li></list></li></list></td>
172+
<td><list><li>apple<list><li>ios<list><li>iosArm64</li><li>iosSimulatorArm64</li><li>iosX64</li></list></li><li>macos<list><li>macosArm64</li><li>macosX64</li></list></li><li>watchos<list><li>watchosArm64</li><li>watchosSimulatorArm64</li><li>watchosX64</li></list></li><li>tvos<list><li>tvosArm64</li><li>tvosSimulatorArm64</li><li>tvosX64</li></list></li></list></li><li>linux<list><li>linuxArm64</li><li>linuxX64</li></list></li><li>windows<list><li>mingwX64</li></list></li></list></td>
173+
</tr>
174+
175+
<!-- PLATFORMS_TABLE_END -->
176+
</table>
177+
<p>
178+
We are working on making the library more portable so that it can be used on more platforms.
179+
</p>
180+
</topic>

0 commit comments

Comments
 (0)