RPC Clients

For each declared service, kotlinx.rpc will generate an actual client implementation that can be used to send requests to a server. You must not use generated code directly. Instead, you should use the APIs that will provide you with the instance of your interface. This generated instance is commonly called a stub in RPC.

To be able to obtain an instance of your service, you need to have an RPCClient. You can call the withService() method on your client:

        val rpcClient: RPCClient

        val myService: MyService = rpcClient.withService<MyService>()

Now you have your client instance that is able to send RPC requests to your server. RPCClient can have multiple services that communicate through it. Conceptually, RPCClient is an abstraction of a client, that is able to convent service requests (represented by RPCCall and RPCField classes) into actual network requests.

You can provide your own implementations of the RPCClient. But kotlinx.rpc already provides one out-of-the-box solution that uses in-house RPC protocol (called kRPC), and we are working on supporting more protocols (with priority on gRPC).

KRPCClient — RPCClient for kRPC Protocol

KRPCClient is an abstract class that implements RPCClient and kRPC protocol logic. The only thing required to be implemented is the transporting of the raw data. Abstract transport is represented by RPCTransport interface.

To implement your own RPCTransport you need to be able to transfer strings and/or raw bytes (Kotlin's ByteArray). Additionally, the library will provide you with integrations with different libraries that are used to work with the network.

See below an example usage of kRPC with a custom transport:

            class MySimpleRPCTransport : RPCTransport {
                val outChannel = Channel<RPCTransportMessage>()
                val inChannel = Channel<RPCTransportMessage>()

                override val coroutineContext: CoroutineContext = Job()

                override suspend fun send(message: RPCTransportMessage) {
                    outChannel.send(message)
                }

                override suspend fun receive(): RPCTransportMessage {
                    return inChannel.receive()
                }
            }

            class MySimpleRPCClient : KRPCClient(rpcClientConfig(), MySimpleRPCTransport())

            val client = MySimpleRPCClient()
            val service: MyService = client.withService<MyService>()
        

Last modified: 13 June 2024