Connect-Kotlin

Connect-Kotlin is a slim library for building browser and gRPC-compatible HTTP APIs. You write a short Protocol Buffer schema and implement your application logic, and Connect generates code to handle marshaling, routing, compression, and content type negotiation. It also generates an idiomatic, type-safe client. Handlers and clients support three protocols: gRPC, gRPC-Web, and Connect's own protocol.

Given a simple Protobuf schema, Connect-Kotlin generates idiomatic Kotlin protocol interfaces and client implementations:

Click to expand ElizaServiceClient.kt

public class ElizaServiceClient(
    private val client: ProtocolClientInterface
) : ElizaServiceClientInterface {
    public override suspend fun say(request: SayRequest, headers: Headers):
        ResponseMessage<SayResponse> = client.unary(
        request,
        headers,
        MethodSpec(
            "buf.connect.demo.eliza.v1.ElizaService/Say",
            buf.connect.demo.eliza.v1.SayRequest::class,
            buf.connect.demo.eliza.v1.SayResponse::class
        )
    )

    public override suspend fun converse(headers: Headers):
        BidirectionalStreamInterface<ConverseRequest, ConverseResponse> = client.stream(
        headers,
        MethodSpec(
            "buf.connect.demo.eliza.v1.ElizaService/Converse",
            buf.connect.demo.eliza.v1.ConverseRequest::class,
            buf.connect.demo.eliza.v1.ConverseResponse::class
        )
    )

    public override suspend fun introduce(headers: Headers):
        ServerOnlyStreamInterface<IntroduceRequest, IntroduceResponse> = client.serverStream(
        headers,
        MethodSpec(
            "buf.connect.demo.eliza.v1.ElizaService/Introduce",
            buf.connect.demo.eliza.v1.IntroduceRequest::class,
            buf.connect.demo.eliza.v1.IntroduceResponse::class
        )
    )
}

Click to expand ElizaServiceClientInterface.kt

public interface ElizaServiceClientInterface {
    public suspend fun say(request: SayRequest, headers: Headers = emptyMap()):
        ResponseMessage<SayResponse>

    public suspend fun converse(headers: Headers = emptyMap()):
        BidirectionalStreamInterface<ConverseRequest, ConverseResponse>

    public suspend fun introduce(headers: Headers = emptyMap()):
        ServerOnlyStreamInterface<IntroduceRequest, IntroduceResponse>
}

This code can then be integrated with just a few lines:

class MainActivity : AppCompatActivity() {
    private lateinit var elizaServiceClient: ElizaServiceClientInterface

    private suspend fun say(sentence: String) {
        // Make a unary request to Eliza.
        val response = elizaServiceClient.say(SayRequest.newBuilder().setSentence(sentence).build())
        val elizaSentence = response.success { success ->
            // Get Eliza's reply from the response.
            success.message.sentence
        }
        // Use the elizaSentence in your views.
    }
}

That’s it! You no longer need to manually define request/response models, specify the exact path of your request, nor worry about the underlying networking transport for your applications!

Quick Start

Head over to our quick start tutorial to get started. It only takes ~10 minutes to complete a working chat app that uses Connect-Kotlin!

Documentation

Comprehensive documentation for everything, including interceptors, streaming, and error handling is available on the connect.build website.

Generation Options

Option	Type	Default	Details
`generateCallbackMethods`	Boolean	`false`	Generate callback signatures for unary methods.
`generateCoroutineMethods`	Boolean	`true`	Generate suspend signatures for unary methods.
`generateBlockingUnaryMethods`	Boolean	`false`	Generate blocking signatures for unary methods.

Example Apps

Example apps are available in /examples. First, run make generate to generate code for the Protobuf plugins.

For the Android example, you can run make installandroid to build and install a fully functional Android application using Connect-Kotlin.

Additionally, there are pure Kotlin examples that demonstrate a simple main executable using Connect-Kotlin:

/examples/kotlin-google-java: A simple Kotlin main executable using Google's Java Protobuf generator plugin
/examples/kotlin-google-javalite: A simple Kotlin main executable using Google's Javalite Protobuf generator plugin

The examples demonstrates:

Using streaming APIs in an Android app
Using Google's Java and Javalite generated data types
Using the Connect protocol
Using the gRPC protocol
Using the gRPC-Web protocol

Contributing

We'd love your help making Connect better!

Extensive instructions for building the library and generator plugins locally, running tests, and contributing to the repository are available in our CONTRIBUTING.md guide. Please check it out for details.

Ecosystem

connect-swift: Swift clients for idiomatic gRPC & Connect RPC
connect-web: TypeScript clients for web browsers
connect-go: Service handlers and clients for GoLang
Buf Studio: web UI for ad-hoc RPCs
connect-crosstest: gRPC and gRPC-Web interoperability tests

Status

This project is in beta, and we may make a few changes as we gather feedback from early adopters. Join us on Slack!

Legal

Offered under the Apache 2 license.

bufbuild/connect-kotlin