Skip to content

Commit c647d4c

Browse files
Mr3zeeMr3zee
committed
Added docs for the gRPC
1 parent 5ce1f7d commit c647d4c

File tree

6 files changed

+271
-3
lines changed

6 files changed

+271
-3
lines changed

‎README.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -156,9 +156,17 @@ When using kRPC you only need to provide a transport or choose from the official
156156

157157
Besides that, one can even provide their own protocol or integration with one to use with services and `kotlinx.rpc` API with it.
158158
Though possible, it is much more complicated way to use the library and generally not needed.
159-
`kotlinx.rpc` aims to provide most common protocols integrations as well as the in-house one called kRPC.
160-
Integrations in progress:
161-
- Integration with [gRPC](https://grpc.io/) (in prototype)
159+
`kotlinx.rpc` aims to provide most common protocols integrations as well as the in-house one called kRPC.
160+
161+
## gRPC integration
162+
Library provides experimental support for the [gRPC](https://grop.io) protocol.
163+
The artifacts are published separately in our [Space repository](https://public.jetbrains.space/p/krpc/packages/maven/grpc)
164+
Current latest version:
165+
166+
![Dynamic XML Badge](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fmaven.pkg.jetbrains.space%2Fpublic%2Fp%2Fkrpc%2Fgrpc%2Forg%2Fjetbrains%2Fkotlinx%2Fkotlinx-rpc-core%2Fmaven-metadata.xml&query=%2F%2Fmetadata%2Fversioning%2Flatest&label=Latest%20dev%20version&color=forest-green&cacheSeconds=60)
167+
168+
See more on gRPC usage in the [docs](https://kotlin.github.io/kotlinx-rpc/grpc-configuration.html).
169+
See also [sample gRPC project](/samples/grpc-app).
162170

163171
## Kotlin compatibility
164172
We support all stable Kotlin versions starting from 2.0.0:

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,12 @@
2525
<toc-element topic="features.topic"/>
2626
<toc-element topic="transport.topic"/>
2727
</toc-element>
28+
<toc-element toc-title="gRPC">
29+
<toc-element topic="grpc-configuration.topic"/>
30+
<toc-element topic="grpc-services.topic"/>
31+
<toc-element topic="grpc-client.topic"/>
32+
<toc-element topic="grpc-server.topic"/>
33+
</toc-element>
2834
</toc-element>
2935
<toc-element topic="strict-mode.topic"/>
3036
<toc-element topic="versions.topic"/>

‎docs/pages/kotlinx-rpc/topics/grpc-client.topic‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
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="Client" id="grpc-client">
7+
8+
<p>
9+
Example of using a gRPC client:
10+
</p>
11+
<code-block lang="Kotlin">
12+
val grpcClient = GrpcClient("localhost", 8080) {
13+
usePlaintext()
14+
}
15+
16+
val recognizer = grpcClient.withService&lt;ImageRecognizer&gt;()
17+
18+
val image = Image {
19+
data = byteArrayOf(0, 1, 2, 3)
20+
}
21+
val result = recognizer.recognize(image)
22+
println("Recognized category: ${result.category}")
23+
24+
grpcClient.cancel()
25+
</code-block>
26+
</topic>

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

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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="Configuration" id="grpc-configuration">
7+
8+
<tldr>
9+
<p>
10+
Artifacts for gRPC integration are published <a href="">separately</a>
11+
and updated frequently not in sync with main releases.
12+
</p>
13+
<p>
14+
<a href="https://maven.pkg.jetbrains.space/public/p/krpc/grpc">
15+
<img alt="Latest dev version"
16+
src="https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fmaven.pkg.jetbrains.space%2Fpublic%2Fp%2Fkrpc%2Fgrpc%2Forg%2Fjetbrains%2Fkotlinx%2Fkotlinx-rpc-core%2Fmaven-metadata.xml&amp;query=%2F%2Fmetadata%2Fversioning%2Flatest&amp;label=Latest%20dev%20version&amp;color=forest-green&amp;cacheSeconds=60"/>
17+
</a>
18+
</p>
19+
</tldr>
20+
21+
<p>
22+
<a href="https://grpc.io">gRPC</a> integration is available in an experimental state.
23+
The artifacts are published separately in our <a
24+
href="https://public.jetbrains.space/p/krpc/packages/maven/grpc">Space repository</a>.
25+
Current latest version can be seen in the badge on top of the page.
26+
</p>
27+
<chapter title="Dependencies configuration" id="dependencies-configuration">
28+
<p>Below is an example of a project setup.</p>
29+
<code>settings.gradle.kts</code>:
30+
<code-block lang="Kotlin">
31+
pluginManagement {
32+
repositories {
33+
gradlePluginPortal()
34+
mavenCentral()
35+
maven("https://maven.pkg.jetbrains.space/public/p/krpc/grpc")
36+
}
37+
}
38+
</code-block>
39+
<p>
40+
<code>build.gradle.kts</code>:
41+
</p>
42+
<code-block lang="Kotlin">
43+
plugins {
44+
kotlin("jvm") version "2.1.0"
45+
kotlin("plugin.serialization") version "2.1.0"
46+
id("org.jetbrains.kotlinx.rpc.plugin") version "&lt;version&gt;"
47+
id("com.google.protobuf") version "0.9.4"
48+
}
49+
50+
repositories {
51+
mavenCentral()
52+
maven("https://maven.pkg.jetbrains.space/public/p/krpc/grpc")
53+
}
54+
55+
dependencies {
56+
implementation("org.jetbrains.kotlinx:kotlinx-rpc-grpc-core:&lt;version&gt;")
57+
implementation("ch.qos.logback:logback-classic:1.5.16")
58+
implementation("io.grpc:grpc-netty:1.69.0")
59+
}
60+
</code-block>
61+
<p>Here <code>&lt;version&gt;</code> comes from the badge above.</p>
62+
<warning>
63+
The setup has only been tested on <code>Kotlin/JVM</code> projects.
64+
</warning>
65+
</chapter>
66+
<chapter title="Protoc setup" id="protoc-setup">
67+
<p>
68+
gRPC requires additional code generation from the <a href="https://github.com/google/protobuf-gradle-plugin">protoc</a>
69+
compiler.
70+
This can be setup up in the following way:
71+
</p>
72+
<code-block lang="Kotlin">
73+
protobuf {
74+
protoc {
75+
artifact = "com.google.protobuf:protoc:4.29.3"
76+
}
77+
78+
plugins {
79+
create("kotlinx-rpc") {
80+
artifact = "org.jetbrains.kotlinx:kotlinx-rpc-protobuf-plugin:&lt;version&gt;:all@jar"
81+
}
82+
83+
create("grpc") {
84+
artifact = "io.grpc:protoc-gen-grpc-java:1.69.0"
85+
}
86+
87+
create("grpckt") {
88+
artifact = "io.grpc:protoc-gen-grpc-kotlin:1.4.1:jdk8@jar"
89+
}
90+
}
91+
92+
generateProtoTasks {
93+
all().all {
94+
plugins {
95+
create("kotlinx-rpc") {
96+
option("debugOutput=protobuf-plugin.log")
97+
option("messageMode=interface")
98+
}
99+
create("grpc")
100+
create("grpckt")
101+
}
102+
}
103+
}
104+
}
105+
</code-block>
106+
</chapter>
107+
</topic>

‎docs/pages/kotlinx-rpc/topics/grpc-server.topic‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
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="Server" id="grpc-server">
7+
8+
<p>
9+
Example of using a gRPC server:
10+
</p>
11+
<code-block lang="Kotlin">
12+
val grpcServer = GrpcServer(8080) {
13+
registerService&lt;ImageRecognizer&gt; { ImageRecognizerImpl() }
14+
}
15+
16+
grpcServer.start()
17+
grpcServer.awaitTermination()
18+
</code-block>
19+
</topic>

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

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
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="Services" id="grpc-services">
7+
8+
<p>
9+
Define a service in the <code>proto</code> folder next to your source sets:
10+
</p>
11+
<code-block>
12+
├── build.gradle.kts
13+
├── settings.gradle.kts
14+
└── src
15+
├── main
16+
│ ├── kotlin
17+
│ │ ├── Client.kt
18+
│ │ ├── ImageRecognizer.kt
19+
│ │ └── Server.kt
20+
│ └── resources
21+
│ └── logback.xml
22+
└── proto
23+
└── image-recognizer.proto
24+
</code-block>
25+
26+
<p>
27+
Inside the file define a service:
28+
</p>
29+
<code-block lang="protobuf">
30+
syntax = "proto3";
31+
32+
message Image {
33+
bytes data = 1;
34+
}
35+
36+
message RecogniseResult {
37+
int32 category = 1;
38+
}
39+
40+
service ImageRecognizer {
41+
rpc recognize(Image) returns (RecogniseResult);
42+
}
43+
</code-block>
44+
<p>
45+
Some code will be generated. The most important ones are <code>interface ImageRecognizer</code>,
46+
<code>interface Image</code> and <code>interface RecogniseResult</code>:
47+
</p>
48+
<code-block lang="Kotlin">
49+
@Grpc
50+
interface ImageRecognizer {
51+
suspend fun recognize(image: Image): RecogniseResult
52+
}
53+
54+
interface RecogniseResult {
55+
val category: Int
56+
57+
companion object
58+
}
59+
60+
interface Image {
61+
val data: ByteArray
62+
63+
companion object
64+
}
65+
</code-block>
66+
<p>
67+
You can implement the <code>ImageRecognizer</code>:
68+
</p>
69+
<code-block lang="Kotlin">
70+
class ImageRecognizerImpl : ImageRecognizer {
71+
override suspend fun recognize(image: Image): RecogniseResult {
72+
val byte = image.data[0].toInt()
73+
delay(100) // heavy processing
74+
val result = RecogniseResult {
75+
category = if (byte == 0) 0 else 1
76+
}
77+
return result
78+
}
79+
}
80+
</code-block>
81+
<p>
82+
Here you can also see the usage of <code>interface RecogniseResult</code>.
83+
To create an instance simple use its <code>invoke</code> extension function:
84+
</p>
85+
<code-block lang="Kotlin">
86+
RecogniseResult {
87+
category = 0
88+
}
89+
</code-block>
90+
91+
<warning>
92+
Current known limitations:
93+
<list>
94+
<li>No streaming</li>
95+
<li>Only primitive types in messages</li>
96+
<li>Mandatory java and kotlin protoc generation in addition to our codegen</li>
97+
<li>Kotlin/JVM project only</li>
98+
</list>
99+
If you encounter other unexpected limitations or bugs,
100+
please <a href="https://github.com/Kotlin/kotlinx-rpc/issues/new?template=bug_report.md">report</a> them
101+
</warning>
102+
</topic>

0 commit comments

Comments
 (0)