kotlinx.rpc is a Kotlin library for adding asynchronous Remote Procedure Call (RPC) services to your applications. Build your RPC with already known language constructs and nothing more!

Quick start

First, create your RPC service and define some methods:

import kotlinx.rpc.RemoteService
import kotlinx.rpc.annotations.Rpc

@Rpc
interface AwesomeService : RemoteService {
    suspend fun getNews(city: String): Flow<String>
}

In your server code define how to respond by simply implementing the service:

class AwesomeServiceImpl(override val coroutineContext: CoroutineContext) : AwesomeService {
    override suspend fun getNews(city: String): Flow<String> {
        return flow { 
            emit("Today is 23 degrees!")
            emit("Harry Potter is in $city!")
            emit("New dogs cafe has opened doors to all fluffy customers!")
        }
    }
}

Then, choose how do you want your service to communicate. For example, you can use integration with Ktor:

fun main() {
    embeddedServer(Netty, 8080) {
        install(RPC)
        routing {
            rpc("/awesome") {
                rpcConfig {
                    serialization {
                        json()
                    }
                }

                registerService<AwesomeService> { ctx -> AwesomeServiceImpl(ctx) }
            }
        }
    }.start(wait = true)
}

To connect to the server use the following Ktor Client setup:

val rpcClient = HttpClient { installRPC() }.rpc {
    url("ws://localhost:8080/awesome")

    rpcConfig {
        serialization {
            json()
        }
    }
}

streamScoped {
    rpcClient.withService<AwesomeService>().getNews("KotlinBurg").collect { article ->
        println(article)
    }
}

Check out our getting started guide for a thorough overview of all components and features.

Configure the project

Plugin dependencies

kotlinx.rpc provides Gradle plugin org.jetbrains.kotlinx.rpc.plugin that will set up code generation in a project.

Example of a setup in a project's build.gradle.kts:

plugins {
    kotlin("multiplatform") version "2.0.21"
    kotlin("plugin.serialization") version "2.0.21"
    id("org.jetbrains.kotlinx.rpc.plugin") version "0.4.0"
}

Runtime dependencies

To use kotlinx.rpc runtime dependencies, add Maven Central to the list of your repositories:

repositories {
    mavenCentral()
}

And now you can add dependencies to your project:

dependencies {
    // Client API
    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.4.0")
    // Server API
    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.4.0") 
    // Serialization module. Also, protobuf and cbor are provided
    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.4.0") 

    // Transport implementation for Ktor
    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.4.0")
    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.4.0")

    // Ktor API
    implementation("io.ktor:ktor-client-cio-jvm:$ktor_version")
    implementation("io.ktor:ktor-server-netty-jvm:$ktor_version")
}

You can see example projects in the samples folder.

Transport

kotlinx.rpc is designed to be transport agnostic. That means that the library aims to provide the best RPC experience regardless of how the resulting messages are transferred. That allows for easy integration into existing solutions, such as Ktor, without the need to rewrite code. Add kotlinx.rpc, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run. With enough time it might even work with avian carriers.

kotlinx.rpc provides its own transfer protocol called kRPC, which takes responsibility for tracking serializing and handling other complex request operations. When using kRPC you only need to provide a transport or choose from the officially supported ones:

• Ktor transport

Besides that, one can even provide their own protocol or integration with one to use with services and kotlinx.rpc API with it. Though possible, it is much more complicated way to use the library and generally not needed. kotlinx.rpc aims to provide most common protocols integrations as well as the in-house one called kRPC.
Integrations in progress:

• Integration with gRPC (in prototype)

Kotlin compatibility

We support all stable Kotlin versions starting from 2.0.0:

• 2.0.0, 2.0.10, 2.0.20, 2.0.21

For a full compatibility checklist, see Versions.

JetBrains Product

kotlinx.rpc is an official JetBrains product and is primarily developed by the team at JetBrains, with contributions from the community.

Support

Community support is available on the Kotlin Slack kotlinx-rpc channel

Reporting Security Vulnerabilities

If you find a security vulnerability in kotlinx.rpc, we kindly request that you reach out to the JetBrains security team via our responsible disclosure process.

Contributing

Please see the contribution guide and the Code of conduct before contributing.