Skip to content

Commit 200719c

Browse files
Mr3zeeMr3zee
committed
Update Writerside docs
1 parent 5501424 commit 200719c

14 files changed

+575
-444
lines changed

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@
2424
<toc-element toc-title="kRPC">
2525
<toc-element topic="configuration.topic"/>
2626
<toc-element topic="features.topic"/>
27-
<toc-element topic="transport.topic"/>
27+
<toc-element topic="krpc-client.topic"/>
28+
<toc-element topic="krpc-server.topic"/>
29+
<toc-element topic="transport.topic">
30+
<toc-element topic="krpc-ktor.topic"/>
31+
</toc-element>
2832
</toc-element>
2933
<toc-element toc-title="gRPC">
3034
<toc-element topic="grpc-configuration.topic"/>

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

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
</p>
3030
<code-block lang="Kotlin">
3131
@Rpc
32-
interface MyService : RemoteService
32+
interface MyService
3333

3434
class MyServiceImpl : MyService
3535

@@ -50,12 +50,31 @@
5050

5151
// T is resolved to MyService,
5252
// but 'body' returns MyServiceImpl
53-
registerService&lt;MyService&gt; { ctx -> MyServiceImpl(ctx) }
53+
registerService&lt;MyService&gt; { MyServiceImpl() }
5454

5555
// Error: T is resolved to MyServiceImpl
56-
registerService { ctx -> MyServiceImpl(ctx) }
56+
registerService { MyServiceImpl() }
5757
</code-block>
5858
</note>
59+
<p>
60+
Annotation type-safety can be enforced recursively:
61+
</p>
62+
<code-block lang="Kotlin">
63+
@Rpc
64+
annotation class Grpc
65+
66+
@Grpc
67+
interface MyGrpcService
68+
69+
fun &lt;@Rpc T&gt; acceptAnyRpcType()
70+
fun &lt;@Grpc T&gt; acceptOnlyGrpcType()
71+
72+
acceptAnyRpcType&lt;MyService&gt;() // OK
73+
acceptAnyRpcType&lt;MyGrpcService&gt;() // OK
74+
75+
acceptOnlyGrpcType&lt;MyService&gt;() // Compiler time error
76+
acceptOnlyGrpcType&lt;MyGrpcService&gt;() // OK
77+
</code-block>
5978

6079
<warning>
6180
This feature is highly experimental and may lead to unexpected behaviour. If you encounter any issues,

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

Lines changed: 69 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -8,97 +8,78 @@
88
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
99
xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
1010
title="Configuration" id="configuration">
11-
<p><code>KrpcConfig</code> is a class used to configure <code>KrpcClient</code> and <code>KrpcServer</code>
12-
(not to be confused with <code>KrpcClient</code> and <code>KrpcServer</code>).
13-
It has two children: <code>KrpcConfig.Client</code> and <code>KrpcConfig.Server</code>.
14-
<code>Client</code> and <code>Server</code> may have shared properties as well as distinct ones.
15-
To create instances of these configurations, DSL builders are provided
16-
(<code>KrpcConfigBuilder.Client</code> class with <code>rpcClientConfig</code> function
17-
and <code>KrpcConfigBuilder.Server</code> class with <code>rpcServerConfig</code> function respectively):
11+
<p>
12+
<code>KrpcConfig</code> is a class used to configure <code>KrpcClient</code> and <code>KrpcServer</code>
13+
(not to be confused with <code>RpcClient</code> and <code>RpcServer</code>).
14+
</p>
15+
<p>
16+
It has two children: <code>KrpcConfig.Client</code> and <code>KrpcConfig.Server</code>.
17+
<code>Client</code> and <code>Server</code> may have shared properties as well as distinct ones.
18+
To create instances of these configurations, DSL builders are provided:
19+
</p>
20+
<list>
21+
<li>
22+
<code>rpcClientConfig</code>
23+
</li>
24+
<li>
25+
<code>rpcServerConfig</code>
26+
</li>
27+
</list>
28+
29+
<code-block lang="kotlin">
30+
val config: KrpcConfig.Client = rpcClientConfig { // same for KrpcConfig.Server with rpcServerConfig
31+
waitForServices = true // default parameter
32+
}
33+
</code-block>
34+
<p>
35+
The following configuration options are available:
36+
</p>
37+
<chapter id="serialization-dsl">
38+
<title>
39+
<code>serialization</code> DSL
40+
</title>
41+
<p>
42+
This parameter defines how serialization should work in RPC services
43+
and is present in both client and server configurations.
44+
</p>
45+
<p>
46+
The serialization process is used to encode and decode data in RPC requests,
47+
so that the data can be transferred through the network.
48+
</p>
49+
<p>
50+
Currently only <code>StringFormat</code> and <code>BinaryFormat</code> from
51+
<a href="https://github.com/Kotlin/kotlinx.serialization">kotlinx.serialization</a> are supported,
52+
and by default you can choose from Json, Protobuf or Cbor formats:
1853
</p>
1954

2055
<code-block lang="kotlin">
21-
val config: KrpcConfig.Client = rpcClientConfig { // same for KrpcConfig.Server with rpcServerConfig
22-
waitForServices = true // default parameter
56+
rpcClientConfig {
57+
serialization {
58+
json { /* this: JsonBuilder from kotlinx.serialization */ }
59+
cbor { /* this: CborBuilder from kotlinx.serialization */ }
60+
protobuf { /* this: ProtobufBuilder from kotlinx.serialization */ }
61+
}
2362
}
2463
</code-block>
25-
<p>The following configuration options are available:</p>
26-
<chapter id="serialization-dsl">
27-
<title>
28-
<code>serialization</code> DSL
29-
</title>
30-
<p>This parameter defines how serialization should work in RPC services
31-
and is present in both client and server configurations.</p>
32-
<p>The serialization process is used to encode and decode data in RPC requests,
33-
so that the data can be transferred through the network.</p>
34-
<p>Currently only <code>StringFormat</code> and <code>BinaryFormat</code> from
35-
<a href="https://github.com/Kotlin/kotlinx.serialization">kotlinx.serialization</a> are supported,
36-
and by default you can choose from Json, Protobuf or Cbor formats:</p>
37-
38-
<code-block lang="kotlin">
39-
rpcClientConfig {
40-
serialization {
41-
json { /* this: JsonBuilder from kotlinx.serialization */ }
42-
cbor { /* this: CborBuilder from kotlinx.serialization */ }
43-
protobuf { /* this: ProtobufBuilder from kotlinx.serialization */ }
44-
}
45-
}
46-
</code-block>
47-
<p>Only last defined format will be used to serialize requests.
48-
If no format is specified, the error will be thrown.
49-
You can also define a custom format.</p>
50-
</chapter>
51-
<chapter id="sharedflowparameters-dsl">
52-
<title>
53-
<code>sharedFlowParameters</code> DSL
54-
</title>
55-
56-
<warning>
57-
These parameters are deprecated since <code>0.5.0</code>. For more information,
58-
see the <a href="0-5-0.topic">migration guide</a>.
59-
</warning>
60-
61-
<code-block lang="kotlin">
62-
rpcClientConfig {
63-
sharedFlowParameters {
64-
replay = 1 // default parameter
65-
extraBufferCapacity = 10 // default parameter
66-
onBufferOverflow = BufferOverflow.SUSPEND // default parameter
67-
}
68-
}
69-
</code-block>
70-
<p>This parameter is needed to decode <code>SharedFlow</code> parameters received from a peer.
71-
<code>MutableSharedFlow</code>, the default function to create a <code>SharedFlow</code> instance,
72-
has the following signature:</p>
73-
74-
<code-block lang="kotlin">
75-
fun &lt;T&gt; MutableSharedFlow(
76-
replay: Int = 0,
77-
extraBufferCapacity: Int = 0,
78-
onBufferOverflow: BufferOverflow = BufferOverflow.SUSPEND
79-
): MutableSharedFlow&lt;T&gt; { /* ... */
80-
}
81-
</code-block>
82-
<p>It creates a <code>SharedFlowImpl</code> class that contains these parameters as properties,
83-
but this class in internal in <code>kotlinx.coroutines</code> and neither <code>SharedFlow</code>,
84-
nor <code>MutableShatedFlow</code> interfaces define these properties,
85-
which makes it impossible (at least for now) to send these properties from one endpoint to another.
86-
But instances of these flows when deserialized should be created somehow,
87-
so to overcome this - configuration parameter is created.
88-
Configuration builder allows defining these parameters
89-
and produces a builder function that is then placed into the <code>KrpcConfig</code>.</p>
90-
</chapter>
91-
<chapter id="waitforservices-dsl">
92-
<title>
93-
<code>waitForServices</code> DSL
94-
</title>
95-
<p><code>waitForServices</code> parameter is available for both client and server.
96-
It specifies the behavior for an endpoint in situations
97-
when the message for a service is received,
98-
but the service is not present in <code>KrpcClient</code> or <code>KrpcServer</code>.
99-
If set to <code>true</code>, the message will be stored in memory,
100-
otherwise, the error will be sent to a peer endpoint,
101-
saying that the message was not handled.
102-
Default value is <code>true</code>.</p>
103-
</chapter>
64+
<p>
65+
Only last defined format will be used to serialize requests.
66+
If no format is specified, a runtime error will be thrown.
67+
You can also define a custom format.
68+
</p>
69+
</chapter>
70+
<chapter id="waitforservices-dsl">
71+
<title>
72+
<code>waitForServices</code> DSL
73+
</title>
74+
<p>
75+
<code>waitForServices</code> parameter is available for both client and server.
76+
It specifies the behavior for an endpoint in situations
77+
when the message for a service is received,
78+
but the service is not present in <code>KrpcClient</code> or <code>KrpcServer</code>.
79+
If set to <code>true</code>, the message will be stored in memory,
80+
otherwise, the error will be sent to a peer endpoint,
81+
saying that the message was not handled.
82+
Default value is <code>true</code>.
83+
</p>
84+
</chapter>
10485
</topic>

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
)
2525

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

3030
suspend fun streamRequest(request: StreamRequest)
@@ -44,15 +44,15 @@
4444
)
4545

4646
@Rpc
47-
interface MyService : RemoteService {
47+
interface MyService {
4848
fun serverStream(): Flow&lt;String&gt; // ok
4949
suspend fun serverStream(): Flow&lt;String&gt; // not ok
5050
suspend fun serverStream(): StreamResult // not ok
5151
}
5252
</code-block>
5353

5454
<note>
55-
Note that flows that are declared in classes (like in <code>StreamResult</code>) require a
55+
Note that flows that are declared in classes (like in <code>StreamRequest</code>) require a
5656
<a href="https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md#contextual-serialization">Contextual</a>
5757
annotation.
5858
</note>

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
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="Client" id="krpc-client">
11+
12+
<chapter title="KrpcClient" id="krpc-client">
13+
<p>
14+
<code>KrpcClient</code> is an abstract class that implements <code>RpcClient</code> and kRPC protocol
15+
logic.
16+
</p>
17+
<chapter title="Initialization" id="initialization">
18+
<p>
19+
The client comes in two forms:
20+
</p>
21+
<list>
22+
<li>
23+
<code>KrpcClient</code>
24+
</li>
25+
<li>
26+
<code>InitializedKrpcClient</code>
27+
</li>
28+
</list>
29+
<p>
30+
The only difference between them is that <code>KrpcClient</code> allows to delay the initialization
31+
of the transport until the first RPC request is sent.
32+
<code>InitializedKrpcClient</code> is initialized right away with a ready <code>KrpcTransport</code>
33+
instance.
34+
</p>
35+
</chapter>
36+
<chapter title="Transport" id="transport">
37+
<p>
38+
The only thing required to be implemented is the transporting of the raw data.
39+
Abstract transport is represented by <code>KrpcTransport</code> interface.
40+
</p>
41+
<p>
42+
To implement your own <code>KrpcTransport</code>
43+
you need to be able to transfer strings and/or raw bytes (Kotlin's <code>ByteArray</code>).
44+
Additionally, the library will provide you with <a href="transport.topic">integrations with different
45+
libraries</a> that are used to work with the network.
46+
</p>
47+
48+
<p>
49+
See below an example usage of kRPC with a custom transport:
50+
</p>
51+
52+
<code-block lang="kotlin">
53+
class MySimpleRpcTransport : KrpcTransport {
54+
val outChannel = Channel&lt;KrpcTransportMessage&gt;()
55+
val inChannel = Channel&lt;KrpcTransportMessage&gt;()
56+
57+
override val coroutineContext: CoroutineContext = Job()
58+
59+
override suspend fun send(message: KrpcTransportMessage) {
60+
outChannel.send(message)
61+
}
62+
63+
override suspend fun receive(): KrpcTransportMessage {
64+
return inChannel.receive()
65+
}
66+
}
67+
68+
class MySimpleRpcClient : KrpcClient(rpcClientConfig(), MySimpleRpcTransport())
69+
70+
val client = MySimpleRpcClient()
71+
val service: MyService = client.withService&lt;MyService&gt;()
72+
</code-block>
73+
</chapter>
74+
</chapter>
75+
</topic>

0 commit comments

Comments
 (0)