GRPC-Kotlin-Multiplatform

2.0.0indexed

Implements client-side gRPC with support for parsing proto3 files, generating corresponding code, and suspending RPC calls. Features a DSL for creating proto objects and supports various proto types.

AndroidJSJVMNativeWasm·TimOrtel/GRPC-Kotlin-Multiplatform

133

Stars

—

Used by

dependents

Health

/ 100

version

badge badge badge badge badge

gRPC Kotlin Multiplatform

This projects implements client-side gRPC for Android, JVM, Native (including iOS), JavaScript and WASM.

Features
Usage
Setup
Example Implementation
Contributing
Implementation details

Features

Supported rpc types:

Supported protobuf versions

	Support status
Proto2	✅ Supported
Proto3	✅ Supported
Editions 2023

Please note that not all features may be available even if the protobuf version is marked as supported.

Supported proto types:

Supported proto options and features:

Legacy options

Features

Code generation:

Proto Struct	Support Status
Messages	✅ Supported
Enums	✅ Supported
Services	✅ Supported

Well-known types:

For reference, see the official documentation. Well-known types support must be enabled in your gradle config (see Setup).

Additional Features

✅ Generates DSL syntax to create messages

Usage

This plugin generates a kotlin class for each message/enum defined in the proto files. Assume you have the following proto file:

syntax = "proto3";

package com.example;

option java_multiple_files = true;

message HelloRequest {
  string greeting = 1;
}

message HelloResponse {
  string response = 1;
}

service HelloService {
  rpc sayHello (HelloRequest) returns (HelloResponse);

  rpc sayHelloMultipleTimes (HelloRequest) returns (stream HelloResponse);
}

Creating proto objects

In your common module, you can create proto objects like this:

val request = helloRequest {
    greeting = "My greeting"
}

Making rpc calls

The request syntax is very similar to the one provided by gRPC Java. Add this code to your common module:

KeepAlive Configuration

You can configure keep-alive to maintain active connections and detect broken connections:

val channel = Channel.Builder()
    .forAddress(/*...*/)
    .withKeepAliveConfig(
        // Exemplary configuration
        KeepAliveConfig.Enabled(
            time = 30.seconds,           // Send keepalive ping every 30 seconds
            timeout = 10.seconds,         // Wait 10 seconds for ping response
            withoutCalls = true          // Send keepalive even when no RPCs are active
        )
    )
    .build()

The keep-alive configuration has no effect on JS/WasmJs.

Trusted Certificates Configuration

By default, on JVM targets the default device certificates are trusted. On Native targets, all certificates from webpki-roots are trusted. Furthermore, you can provide additional certificates that the channel should trust when establishing TLS connections. Both CA certificates and leaf/self-signed certificates are accepted:

val channel = Channel.Builder()
    .forAddress(/*...*/)
    .withTrustedCertificates(
        listOf(
            Certificate.fromPem(/* PEM string */),
            Certificate.fromPem(/* another PEM */)
        )
    )
    .build()

If only the certificates added using withTrustedCertificates should be trusted, call trustOnlyProvidedCertificates:

val channel = Channel.Builder()
    .forAddress(/*...*/)
    .withTrustedCertificates(/*...*/)
    .trustOnlyProvidedCertificates()
    .build()

The trusted certificate configuration has no effect on JS/WasmJs.

Client Identity Configuration

The withClientIdentity function allows the client to present its own certificate and private key during the TLS handshake. This identity pair is used by the server to authenticate the client before allowing requests.

You can configure the channel to use a client identity as follows:

val channel = Channel.Builder()
    .forAddress(/*...*/)
    .withClientIdentity(
        certificate = Certificate.fromPem(/* client certificate PEM */),
        key = PrivateKey.fromPem(/* private key PEM */)
    )
    .build()

The client identity configuration has no effect on JS/WasmJs.

Working with well known types

`Any` Message Extensions

Example: `wrap`

Wraps a message inside an Any message.

val myMessage = myMessage {} // Some message
val wrapped = Any.wrap(myMessage)

Example: `unwrap`

Extracts a message from an Any object.

val extractedMessage: MyMessage = wrapped.unwrap(MyMessage.Companion)

Example: `isType`

Checks if an Any object holds a specific message type.

if (wrapped.isType(MyMessage.Companion)) {
    println("The message is of type MyMessage")
}

`Duration` Extensions

Example: `ofSeconds`

Creates a Duration from seconds.

val duration = Duration.ofSeconds(120)

Example: `ofMillis`

Creates a Duration from milliseconds.

val duration = Duration.ofMillis(500)

Example: `fromDuration`

Creates a Duration from kotlin.time.Duration.

val duration = Duration.fromDuration(1.5.seconds)

Example: `toDuration`

Converts a Duration to kotlin.time.Duration.

val kotlinDuration: kotlin.time.Duration = duration.toDuration()

`Timestamp` Extensions

Example: `fromInstant`

Creates a Timestamp from Instant.

val timestamp = Timestamp.fromInstant(Instant.now())

Example: `toInstant`

Converts a Timestamp to Instant.

val instant: Instant = timestamp.toInstant()

Unknown Fields Support

Unknown fields are automatically captured when parsing messages and also serialized back to the wire. You can access them using the generated property:

class ExampleMessage {
    val unknownFields: List<UnknownField>
}

Intercepting Calls

You can intercept calls to modify what is sent to the server and received from the server. Example:

Using extensions

Forward declarations are currently not supported.

Proto editions support extensions. Extension fields are not generated as part of the message itself, but must instead be set indirectly on the extensions property.

As an example, consider the following proto file:

// sample.proto

edition = "2023";

message MyMessage {
  string regularField = 1;
  extensions 2 to 5;
}

extend MyMessage {
  string myExtension = 2;
}

You can construct a message of type MyMessage like this:

val msg = Sample.MyMessage(
    regularField = "val1", 
    extensions = buildExtensions {
        set(Sample.myExtension, "val2")
    }
)

The values from extensions can be read from a message like this:

val msg: Sample.MyMessage = // ...
val value = msg.extensions[Sample.myExtension]

When deserializing a message received from the server, all known extensions for the message type are considered.

Setup

In your top-level build.gradle.kts, add the following:

buildscript {
    repositories {
        //...
        gradlePluginPortal()
    }

    // ...
}

Common Module build.gradle.kts

Add the following to your plugins block:

plugins {
    kotlin("multiplatform")

    //...
    id("io.github.timortel.kmpgrpc.plugin") version "<latest version>"
}

Add the library as a dependency:

repositories {
    // ...
    mavenCentral()
}

kotlin {
    
    applyDefaultHierarchyTemplate()
    
    
}

kmpGrpc {
    
    common() 
    jvm()
    android()
    js()
    native() 

    
    
    includeWellKnownTypes = 
    
    
    internalVisibility = 

    
    namingStrategy = NamingStrategy.KOTLIN_IDIOMATIC
    
    
    protoSourceFolders = project.files()
}

Example Implementation

See an example implementation of an Android app and an iOS app in the examples folder.

Building locally

To build the native targets locally, you will need to have rust installed on your local machine. Once setup, you can run the following Gradle commands:

To build the library gradle kmp-grpc-core:publishToMavenLocal
To build the plugin gradle kmp-grpc-plugin:publishToMavenLocal

By default, kmp-grpc-core prints trace logs. To deactivate, build the library with -Pio.github.timortel.kmp-grpc.internal.native.release=true.

Contributing

Feel free to implement improvements, bug fixes and features and create a pull request.

Implementation details

How does it work internally?

The plugin generates kotlin code for all provided proto files. No protoc is needed. The networking code is handled by gRPC for JVM and by tonic for all native targets. For JavaScript, the requests are handled by ktor.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

kotlin-fhir★ 63

ohs-foundationLean, fast HL7 FHIR data-model implementation with minimal generated classes, JSON-only serialization, multi-version support, and a tiny runtime footprint for efficient healthcare data handling.Shared: web, wasm, kotlin-native

TextToSpeechKt★ 57

Marc-JBCross-platform text-to-speech library enabling speech synthesis with coroutine support. Features include volume, pitch, and rate adjustments, with Compose integration for enhanced functionality.Shared: web, wasm, kotlin-native

kotlinx-benchmark★ 635

KotlinToolkit for running benchmarks on multiplatform code, offering low noise, reliable results, statistical analysis, and detailed performance reports. Supports various target configurations and custom benchmark profiles.Shared: web, wasm, kotlin-native

wgpu4k★ 110

wgpu4kCreates WebGPU bindings for web, desktop, and mobile, enabling cross-platform graphics development. Offers example executions and is progressing through API implementation and refinement phases.Shared: web, wasm, kotlin-native

i18n4k★ 109

comahe-deHandles internationalization in programs, offering `Locale` and `LocalizedString` classes, parameterized messages, and code generation for message access. Supports inline translations and optimized message files.Shared: kotlin-native, gradle-plugin, code-generation

KmpRealTimeLogger★ 49

kdroidFilterCross-platform logging library mimics Android's Log API, supports live log broadcasting, configurable log levels, and real-time monitoring via a client application using mDNS and WebSocket.Shared: web, wasm, kotlin-native

`double`	`Double`
`float`	`Float`
`int32`	`Int`
`int64`	`Long`
`uint32`	`UInt`
`uint64`	`ULong`
`sint32`	`Int`
`sint64`	`Long`
`fixed32`	`UInt`
`fixed64`	`ULong`
`sfixed32`	`Int`
`sfixed64`	`Long`
`bool`	`Boolean`
`string`	`String`
`bytes`	`ByteArray`

`field_presence`	✅	✅
`repeated_field_encoding`	✅	✅
`enum_type`	✅	✅
`json_format`	⏳ Planned	⏳ Planned
`message_encoding`	⏳ Planned	⏳ Planned
`utf8_validation`	❌	❌
`default_symbol_visibility`		✅
`(pb.java).nest_in_file_class`		✅
`enforce_naming_style`		⏳ Planned

`Unary`	✅	✅	✅	✅
`Client-streaming`	✅	✅	❌	❌
`Server-streaming`	✅	✅	✅	✅
`Bidi-streaming`	✅	✅	❌	❌

`java_package`	✅	✅	✅
`java_outer_classname`	✅	✅	✅
`java_multiple_files`	✅	✅	✅
`deprecated`	✅	✅	✅
`packed`	✅	✅	✅
`default` enum-option	✅	✅	✅
`optimize_for`	❌	❌	❌

`any.proto`	✅ Supported
`api.proto`	✅ Supported
`descriptor.proto`	✅ Supported
`duration.proto`	✅ Supported
`empty.proto`	✅ Supported
`field_mask.proto`	✅ Supported
`source_context.proto`	✅ Supported
`struct.proto`	✅ Supported
`timestamp.proto`	✅ Supported
`type.proto`	✅ Supported
`wrappers.proto`	✅ Supported

GRPC-Kotlin-Multiplatform

gRPC Kotlin Multiplatform

Table of contents

Features

Supported rpc types:

Supported protobuf versions

Supported proto types:

Supported proto options and features:

Legacy options

Features

Code generation:

Well-known types:

Additional Features

Usage

Creating proto objects

Making rpc calls

KeepAlive Configuration

Trusted Certificates Configuration

Client Identity Configuration

Working with well known types

Any Message Extensions

Example: wrap

Example: unwrap

Example: isType

Duration Extensions

Example: ofSeconds

Example: ofMillis

Example: fromDuration

Example: toDuration

Timestamp Extensions

Example: fromInstant

Example: toInstant

Unknown Fields Support

Intercepting Calls

Using extensions

Setup

Common Module build.gradle.kts

Example Implementation

Building locally

Contributing

Implementation details

How does it work internally?

License

Related libraries

gRPC Kotlin Multiplatform

Table of contents

Features

Supported rpc types:

Supported protobuf versions

Supported proto types:

Supported proto options and features:

Legacy options

Features

Code generation:

Well-known types:

Additional Features

Usage

Creating proto objects

Making rpc calls

KeepAlive Configuration

Trusted Certificates Configuration

Client Identity Configuration

Working with well known types

Any Message Extensions

Example: wrap

Example: unwrap

Example: isType

Duration Extensions

Example: ofSeconds

Example: ofMillis

Example: fromDuration

Example: toDuration

Timestamp Extensions

Example: fromInstant

Example: toInstant

Unknown Fields Support

Intercepting Calls

Using extensions

Setup

Common Module build.gradle.kts

`Any` Message Extensions

Example: `wrap`

Example: `unwrap`

Example: `isType`

`Duration` Extensions

Example: `ofSeconds`

Example: `ofMillis`

Example: `fromDuration`

Example: `toDuration`

`Timestamp` Extensions

Example: `fromInstant`

Example: `toInstant`

`Any` Message Extensions

Example: `wrap`

Example: `unwrap`

Example: `isType`

`Duration` Extensions

Example: `ofSeconds`

Example: `ofMillis`

Example: `fromDuration`

Example: `toDuration`

`Timestamp` Extensions

Example: `fromInstant`

Example: `toInstant`