grpc / grpc-kotlin

Kotlin gRPC implementation. HTTP/2 based RPC

gRPC – An RPC library and framework

gRPC is a modern, open source, high-performance remote procedure call (RPC) framework that can run anywhere. gRPC enables client and server applications to communicate transparently, and simplifies the building of connected systems.

Homepage:	grpc.io
Mailing List:	[email protected]

To start using gRPC

To maximize usability, gRPC supports the standard method for adding dependencies to a user's chosen language (if there is one). In most languages, the gRPC runtime comes as a package available in a user's language package manager.

For instructions on how to use the language-specific gRPC runtime for a project, please refer to these documents

• C++: follow the instructions under the src/cpp directory
• C#/.NET: NuGet packages Grpc.Net.Client, Grpc.AspNetCore.Server
• Dart: pub package grpc
• Go: go get google.golang.org/grpc
• Java: Use JARs from Maven Central Repository
• Kotlin: Use JARs from Maven Central Repository
• Node: npm install @grpc/grpc-js
• Objective-C: Add gRPC-ProtoRPC dependency to podspec
• PHP: pecl install grpc
• Python: pip install grpcio
• Ruby: gem install grpc
• WebJS: follow the grpc-web instructions

Per-language quickstart guides and tutorials can be found in the documentation section on the grpc.io website. Code examples are available in the examples directory.

Precompiled bleeding-edge package builds of gRPC master branch's HEAD are uploaded daily to packages.grpc.io.

To start developing gRPC

Contributions are welcome!

Please read How to contribute which will guide you through the entire workflow of how to build the source code, how to run the tests, and how to contribute changes to the gRPC codebase. The "How to contribute" document also contains info on how the contribution process works and contains best practices for creating contributions.

Troubleshooting

Sometimes things go wrong. Please check out the Troubleshooting guide if you are experiencing issues with gRPC.

Performance

See the Performance dashboard for performance numbers of master branch daily builds.

Concepts

See gRPC Concepts

About This Repository

This repository contains source code for gRPC libraries implemented in multiple languages written on top of a shared C++ core library src/core.

Libraries in different languages may be in various states of development. We are seeking contributions for all of these libraries:

Language	Source
Shared C++ [core library]	src/core
C++	src/cpp
Ruby	src/ruby
Python	src/python
PHP	src/php
C# (core library based)	src/csharp
Objective-C	src/objective-c

Language	Source repo
Java	grpc-java
Kotlin	grpc-kotlin
Go	grpc-go
NodeJS	grpc-node
WebJS	grpc-web
Dart	grpc-dart
.NET (pure C# impl.)	grpc-dotnet
Swift	grpc-swift

grpc-kotlin's Issues

Client stub should not take Metadata headers parameter

The current generated stub takes headers as parameter

suspend fun sayHello(request: HelloRequest, headers: Metadata = Metadata()): HelloReply

To my understanding, the headers is more for facilities like interceptors. For example, tracing, client side interceptor puts trace ID into headers, then server side interceptor consumes the trace ID. People may misuse it to carry business logic into it by exposing it on stub.

README: add download, setup and build instructions

For an example, see https://github.com/grpc/grpc-java/blob/master/README.md.

RouteGuideClient.kt: drop Printer interface

@lowasser, I'm trying to keep the tutorial example as simple as possible.

The RouteGuideServer simply uses println() to generate output

Could we use println() in RouteGuideClient instead of defining and using the Printer interface?

  interface Printer {
    companion object {
      val stdout = object : Printer {
        override fun println(str: String) {
          System.out.println(str)
        }
      }
    }
    fun println(str: String)
  }

Automate Gradle publish

grpc-kotlin-compiler should be able to build on windows

In order for us to truly run tests on Windows, we need to be able to build the protoc plugin on Windows. Right now we receive the following error:

Execution failed for task ':grpc-kotlin-compiler:generateTestProto'.
> protoc: stdout: . stderr: --grpckt_out: protoc-gen-grpckt: %1 is not a valid Win32 application.

Once we can build the plugin on Windows as expected, we can add windows-latest to the operating system matrix in our github actions config. This may be fixed once we resolve #82 .

Ensure that dokka docs are published to Maven Central

cc @jamesward

Explicitly target some version of Java

When built with Java 11, the Gradle module metadata published alongside the pom requires any downstream library to use Java 11. If a downstream library wants to target Java 8, Gradle complains:

- Variant 'runtimeElements' capability io.grpc:grpc-kotlin:0.1:
    - Incompatible attribute:
        - Required org.gradle.jvm.version '8' and found incompatible value '11'.

I was able to fix this locally with the classic:

compileJava {
    sourceCompatibility = '1.8'
    targetCompatibility = '1.8'
}

Ideally I can target Android API 19+, so 1.8 would be ideal.

Trailers lost when throwing StatusException/StatusRuntimeException in coroutine server method

Currently, trailing headers are lost when a coroutine gRPC method implementation sets trailers on a thrown StatusException/StatusRuntimeException. I believe the fix is to update this portion of the code to call Status.trailersFromThrowable(failure) and return it if non-null instead of always returning an empty GrpcMetadata():

grpc-kotlin/stub/src/main/java/io/grpc/kotlin/ServerCalls.kt

Line 253 in be5c1d0

else -> Status.fromThrowable(failure)

Rich grpc Error model management

Hello,

I can't find in examples or (light) documentation how to use hRPC rich error model.
For exemple how to reply with a GRPC_STATUS_INTERNAL or GRPC_STATUS_UNAUTHENTICATED from server side ?

Publish to Maven

Gradle installDist task should install protoc + plugin if needed

The gradle installDist task should have the necessary task dependencies to ensure that protoc and the Kotlin plugin get fetched and installed as necessary.

Build failure: application requires a java runtime environment x.y.z

Exception thrown during sample project build

environment: jdk8

Provide a way to propagate a custom context to CoroutineContext

Currently, CoroutineContext could be customized with AbstractCoroutineServerImpl constructor.

grpc-kotlin/stub/src/main/java/io/grpc/kotlin/AbstractCoroutineServerImpl.kt

Line 29 in 2f3d86b

val context: CoroutineContext = EmptyCoroutineContext

And it is combined with GrpcContextElement that captures a context from the current thread and propagates it.

grpc-kotlin/stub/src/main/java/io/grpc/kotlin/ServerCalls.kt

Line 199 in 2f3d86b

context + GrpcContextElement.current(),

However, a CoroutinContext injected by users could not propagate any context from the current thread, because it was instantiated when the Coroutine stub is created.

We can use a hack that was suggested by @anuraaga, line/armeria#2669 (comment)

internal object ArmeriaContext: CoroutineContext {
    override fun <R> fold(initial: R, operation: (R, CoroutineContext.Element) -> R): R =
            EmptyCoroutineContext.fold(initial, operation)

    override fun <E : CoroutineContext.Element> get(key: CoroutineContext.Key<E>): E? =
            EmptyCoroutineContext.get(key)

    override fun minusKey(key: CoroutineContext.Key<*>): CoroutineContext =
            EmptyCoroutineContext.minusKey(key)

    override fun plus(context: CoroutineContext): CoroutineContext {
        val requestCtx: RequestContext = RequestContext.current()
        return requestCtx.contextAwareExecutor().asCoroutineDispatcher() + context
    }
}

We don't think this is a nice approach. If AbstractCoroutineServerImpl get CoroutineContext from a method then constructor parameter, gRPC-Kotlin users can easily propagate their context to CoroutineContext.

abstract class AbstractCoroutineServerImpl(
        val defaultContext: CoroutineContext = EmptyCoroutineContext
) : BindableService {
    open fun context(): CoroutineContext = defaultContext
}

class UserService: XXXCoroutineImplBase() {
    override fun context(): CoroutineContext {
        return ServiceRequestContext.current().contextAwareExecutor().asCoroutineDispatcher()
    }
}

Do you think this change makes sense, I could make a PR. 😀

/cc @anuraaga

Investigate dependencies for JDK 9+ in Maven Projects

Using this in Maven projects with JDK9+ doesn't work. So maybe the stub should depend on javax.annotation:javax.annotation-api ?

cannot find symbol
[ERROR]   symbol:   class Generated
[ERROR]   location: package javax.annotation

Travis build is broken

It has been broken for a couple of days now:

cc @bshaffer

Client stub & server ImplBase share the same interface

This is my personal opinion, I feel if the Client stub & server ImplBase are organized in this way:

interface Greeter {
  suspend fun sayHello(request: HelloRequest): HelloReply
}

class GreeterCoroutineStub(...): AbstractCoroutineStub<GreeterCoroutineStub>(...), Greeter
abstract class GreeterCoroutineImplBase(...): AbstractCoroutineServerImpl(...), Greeter

Then we can get some benefits like:

1. The dependency will be declared with the interface, makes it easier to mock in unit tests.
2. Stub & ImplBase is interchangeable with injection, so you can use a stub to call a remote service, but use ImplBase directly if it's living in the same JVM (I do have this kind of case, if a component is small so I just put it in the current service, but it may be separated out if it grows big).

[Feature request] Rx-Java support

Can you please implement Rx-Java support for grpc stubs in future to have possibility use coroutines or Rx?

Problem with underscores in RPC method names

Hello, I faced one issue with proto generation using grpc-kotlin.
Looks like grpc-kotlin and grpc-java handle method names in different ways.
For example:

syntax = "proto3";
package io.grpc.examples.helloworld;
option java_multiple_files = true;
service Foo {
    rpc say_hello (HelloRequest) returns (HelloReply);
}
message HelloRequest {}
message HelloReply {}

Result:

e: /Users/ivanbalaksha/work/kotlin-grpc-bug/build/generated/source/proto/main/grpckt/io/grpc/examples/helloworld/TestGrpcKt.kt: (50, 15): Unresolved reference: getSay_helloMethod
e: /Users/ivanbalaksha/work/kotlin-grpc-bug/build/generated/source/proto/main/grpckt/io/grpc/examples/helloworld/TestGrpcKt.kt: (80, 28): Unresolved reference: getSay_helloMethod

Method signature in java:

public static io.grpc.MethodDescriptor<io.grpc.examples.helloworld.HelloRequest,
      io.grpc.examples.helloworld.HelloReply> getSayHelloMethod() {

In style guide, it is recommended to use CamelCase, but I'm working with an existing project where all RPCs defined in this way, and it is not possible to change it.
I think it is super important to keep method names generation consistent between grpc-java and grpc-kotlin.

API reference docs have a new home, adjust links and gh-pages

• Update link to gRPC-Kotlin API reference docs in the README. The link to use is now: https://javadocs.dev/io.grpc/grpc-kotlin-stub/latest/ - #110
• Remove gRPC-Kotlin API reference docs from gh-pages #107
  I doubt that too many folks have saved links to the hosted gh-pages, so we might eventually just delete the gh-pages branch altogether.

Context: #74 (comment)

Consider adding a RELEASING.md file like grpc-java

Cf. https://github.com/grpc/grpc-java/blob/master/RELEASING.md

kotlin libs should use implementation as oppose to compile?

e.g., https://github.com/Kotlin/kotlinx.coroutines#gradle

Add example with build.gradle.kts configuration

Existing example project based on groovy Gradle configuration. Kotlin script support added long time ago to Gradle https://docs.gradle.org/current/userguide/kotlin_dsl.html.
It would be nice to have kts example too

Cleaner object creation

In the sample code you initialize a HelloRequest object with:

val request = HelloRequest.newBuilder().setName(name).build()

It would be a big help if you could generate a Kotlin builder for each user protobuf object:

fun helloRequest(block: HelloRequest.Builder.() -> Unit): HelloRequest =
    HelloRequest.newBuilder().let {
        block.invoke(it)
        it.build()
    }

which would allow for much cleaner object creation:

 val request = helloRequest { this.name = name }

One of your fellow Googlers uses this approach and it makes for less cluttered user code.

Automate deployment of API reference docs

@jamesward spoke of adapting a deploy app that he wrote and used elsewhere. Deployment wouldn't be to gh-pages`.

@jamesward - once this is setup, and you know the link to the API reference docs, let me know so that I can make the corresponding update to the link used on the grpc.io site - grpc/grpc.io#218

interop tests fails against java server

Interop fails w/ Kotlin Client vs Java Server:

# In grpc-java
./run-test-server.sh --use_tls=true

# In grpc-kotlin
./run-test-client.sh --server_host_override=foo.test.google.fr --use_test_ca=true --test_case=unimplemented_service

Or, Java Client vs Kotlin Server

# in grpc-kotlin
./run-test-server.sh --use_tls=true

# In grpc-java
./run-test-client.sh --server_host_override=foo.test.google.fr --use_test_ca=true --test_case=unimplemented_service

Kotlin client + Kotlin server passed though.

Add support for grpc-dagger

If I try to use grpc-dagger with a service generated by protoc-gen-grpc-kotlin, I am getting the following error:

e: /Users/..../FooService.java:6: error: FooServiceGrpcKt is not a gRPC service class
@dagger.grpc.server.GrpcService(grpcClass = FooServiceGrpcKt.class)

@GrpcService(grpcClass = FooServiceGrpcKt::class)
class Foo @Inject constructor() : FooServiceGrpcKt.FooServiceCoroutineImplBase()

Are you thinking of adding support for it, or am I just doing something the wrong way?

Multiple emissions in a row in flow

I have an rpc which returns a flow

override fun joinRoom(requests: Flow<JoinRoomRequest>): Flow<JoinRoomResponse> = channelFlow {}

When I am receiving a certain request I am sending back multiple responses. Something like

producer.send(response1)
producer.send(response2)
producer.send(response3)

Most of times client receives only the last response. If I add delay(100) between emissions it works as expected. Could you please give me an idea what could be wrong?
Thanks

Support for Kotlin native / multiplatform

Great to see an official Kotlin gRPC library!

I wonder if support for Kotlin native is planned?

Thanks!

Add JDK 7 Source & Target Gradle Configs

Remove gRPC-Kotlin API reference docs from gh-pages

The latest API reference docs are now available from

https://javadocs.dev/io.grpc/grpc-kotlin-stub/latest/

so remove the docs previously published to gh-pages (#5).

Context: #74 (comment)

Library bundles Kotlin runtime

When I attempt to build the examples project Gradle warns:

w: Some JAR files in the classpath have the Kotlin Runtime library bundled into them. This may cause difficult to debug problems if there's a different version of the Kotlin Runtime library in the classpath. Consider removing these libraries from the classpath
w: /Users/andrewparmet/.m2/repository/io/grpc/grpc-kotlin/0.1/grpc-kotlin-0.1.jar: Library has Kotlin runtime bundled into it

This causes issues when I use grpc-kotlin as a dependency in a prototype project of my own with kotlinOptions.allWarningsAsErrors = true.

When I tried to move the kotlin-coroutines and kotlin-reflect dependencies down from compile to runtime, naturally the plugin fails to run:

protoc: stdout: . stderr: Exception in thread "main" java.lang.NoClassDefFoundError: kotlinx/coroutines/flow/Flow

Is there a way around this? I can ignore the warning with -Xskip-runtime-version-check but that's not a great long-term solution.

Problem with underscores in RPC names

Hello, I upgraded to version 0.1.2 and realized that compilation still failing.
I added to examples/src/main/proto/hello_world.proto

+  rpc say_hello (HelloRequest) returns (HelloReply);

And I got

> Task :compileKotlin FAILED
e: /Users/ivanbalaksha/work/grpc-kotlin-upstream/examples/build/generated/source/proto/main/grpckt/io/grpc/examples/helloworld/HelloWorldGrpcKt.kt: (41, 25): Unresolved reference: getsay_helloMethod
e: /Users/ivanbalaksha/work/grpc-kotlin-upstream/examples/build/generated/source/proto/main/grpckt/io/grpc/examples/helloworld/HelloWorldGrpcKt.kt: (84, 19): Unresolved reference: getSay_helloMethod
e: /Users/ivanbalaksha/work/grpc-kotlin-upstream/examples/build/generated/source/proto/main/grpckt/io/grpc/examples/helloworld/HelloWorldGrpcKt.kt: (133, 32): Unresolved reference: getSay_helloMethod

Looks like wrong build was uploaded

io.grpc:grpc-kotlin-stub-lite includes io.grpc:grpc-kotlin-stub

Hi! Here is my runtimeClasspath dependencies

runtimeClasspath - Runtime classpath of compilation 'main' (target  (jvm)).
+--- org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.3.72
|    +--- org.jetbrains.kotlin:kotlin-stdlib:1.3.72
|    |    +--- org.jetbrains.kotlin:kotlin-stdlib-common:1.3.72
|    |    \--- org.jetbrains:annotations:13.0
|    \--- org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.72
|         \--- org.jetbrains.kotlin:kotlin-stdlib:1.3.72 (*)
+--- org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7
|    +--- org.jetbrains.kotlin:kotlin-stdlib:1.3.71 -> 1.3.72 (*)
|    \--- org.jetbrains.kotlin:kotlin-stdlib-common:1.3.71 -> 1.3.72
+--- io.grpc:grpc-okhttp:1.27.2
|    +--- io.grpc:grpc-core:1.27.2
|    |    +--- io.grpc:grpc-api:1.27.2 -> 1.28.0
|    |    |    +--- io.grpc:grpc-context:1.28.0
|    |    |    +--- com.google.errorprone:error_prone_annotations:2.3.4
|    |    |    +--- com.google.code.findbugs:jsr305:3.0.2
|    |    |    +--- org.codehaus.mojo:animal-sniffer-annotations:1.18
|    |    |    \--- com.google.guava:guava:28.1-android
|    |    |         +--- com.google.guava:failureaccess:1.0.1
|    |    |         +--- com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava
|    |    |         +--- org.checkerframework:checker-compat-qual:2.5.5
|    |    |         \--- com.google.j2objc:j2objc-annotations:1.3
|    |    +--- com.google.code.gson:gson:2.8.6
|    |    +--- com.google.android:annotations:4.1.1.4
|    |    +--- com.google.errorprone:error_prone_annotations:2.3.4
|    |    \--- io.perfmark:perfmark-api:0.19.0
|    |         \--- com.google.code.findbugs:jsr305:3.0.2
|    +--- com.squareup.okio:okio:1.13.0
|    \--- com.squareup.okhttp:okhttp:2.5.0
+--- io.grpc:grpc-stub:1.27.2 -> 1.28.0
|    \--- io.grpc:grpc-api:1.28.0 (*)
+--- io.grpc:grpc-protobuf-lite:1.27.2 -> 1.28.0
|    +--- io.grpc:grpc-api:1.28.0 (*)
|    +--- com.google.protobuf:protobuf-javalite:3.11.0
|    \--- com.google.guava:guava:28.1-android (*)
\--- io.grpc:grpc-kotlin-stub-lite:0.1.3
     +--- org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.3 -> 1.3.7 (*)
     +--- io.grpc:grpc-protobuf-lite:1.28.0 (*)
     +--- io.grpc:grpc-stub:1.28.0 (*)
     +--- io.grpc:grpc-kotlin-stub:0.1.3
     |    +--- org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.3 -> 1.3.7 (*)
     |    +--- io.grpc:grpc-protobuf:1.28.0
     |    |    +--- io.grpc:grpc-api:1.28.0 (*)
     |    |    +--- com.google.protobuf:protobuf-java:3.11.0
     |    |    +--- com.google.guava:guava:28.1-android (*)
     |    |    +--- com.google.api.grpc:proto-google-common-protos:1.17.0
     |    |    \--- io.grpc:grpc-protobuf-lite:1.28.0 (*)
     |    +--- io.grpc:grpc-stub:1.28.0 (*)
     |    \--- javax.annotation:javax.annotation-api:1.2
     \--- javax.annotation:javax.annotation-api:1.2

As you can see io.grpc:grpc-kotlin-stub-lite:0.1.3 includes io.grpc:grpc-kotlin-stub:0.1.3.
I think this is not correct.

This is my dependencies. Maybe i do something wrong?

    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${coroutinesVersion}"

    implementation "io.grpc:grpc-okhttp:$grpcVersion"
    implementation "io.grpc:grpc-stub:$grpcVersion"
    implementation "io.grpc:grpc-protobuf-lite:$grpcVersion"
    implementation "io.grpc:grpc-kotlin-stub-lite:$grpcktVersion"

    compileOnly "javax.annotation:javax.annotation-api:1.2"

Android sample

Could you please provide example project for android?

add support for grpc-protobuf-lite

We are currently using gRPC on a Kotlin based Android project and as grpc-java documentation recommends we are using the lite version of the runtime (grpc-protobuf-lite).

Right now grpc-kotlin-stub depends on grpc-protobuf which causes our gradle build to fail if we don't explicitly exclude grpc-protobuf from grpc-kotlin-stub.

I don't like the idea of having to exclude transitive dependencies, are there any plans on releasing a grpc-kotlin-stub-lite?

Publish API reference to gh-pages

This issue is to ensure that we don't forget to a least manually publish a first version. Ideally we should automate the process to the extent possible (e.g., at least the API doc generation part, maybe leaving the actual merging into gh-pages as a manual step). /cc @dwiner

Depends on #4.

Publication of a development road map?

I am really excited to see this repo begin to take shape. I was curious to know if there were plans to publish a road map of the work being done and how the community can get involved.

I author https://github.com/marcoferrer/kroto-plus and would love to be able to contribute to this in any way I can. I'm assuming community discussions are going to take place in the grpc io google group?

Support for Kotlin DSL style builders

Instead of relying on Java builders it would be great if this library supported Kotlin DSL, e.g. given

service HelloWorldAPI {
    rpc HelloWorld(HelloWorldRequest) returns (HelloWorldResponse);
}

message HelloWorldRequest {
    string hello_message = 1;
}

message HelloWorldResponse {
    string hello_response = 1;
}

It would be great if we could construct proto objects as

val hello = HelloWorldRequest {
  helloMessage = "hello"
}

instead of using ugly Java builders

val hello = HelloWorldRequest.newBuilder()
  .setHelloMessage("hello")
  .build()

Current Implementation Design

Reviewing the current implementation there are some choices that stood out that remind me of early versions of Kroto. A few of these caused bugs that were difficult to debug due to the way Kotlin resolves extension function receivers in nested scopes. Leaking resources and breaking structured concurrency.

Is there a formal process for providing feedback or should feedback be reserved until after an initial release?

Remove native binarys and update instructions to use protoc jars

Canteen makes jars executable by preprending a launcher:
https://github.com/salesforce/grpc-java-contrib/tree/master/canteen

We'd need to build a gradle plugin for it.

Or, add jar support to the protobuf-gradle-plugin:
google/protobuf-gradle-plugin#168

Rename `example` to `examples`

@bshaffer while I much prefer that folder names be singular, for sake of uniformity, I'd nonetheless suggest that we rename example to examples so as to match the (1) folder name as used under grpc/grpc and grpc/grpc-java (2) package name in io.grpc.examples. WDYT?

mismatch between `grpc-java` protobuf generated classes and `grpc-kotlin` expected classes

Unsure whether this should be created under protobuf or grpc-kotlin but given simple hello.proto

syntax = "proto3";

option java_multiple_files = false;
package hello;

service Hello {
    rpc hello(Request) returns (Response);
}

message Request {
    string name = 1;
}

message Response {
    string greeting = 1;
}

GRPC Java generates wrapper HelloOuterClass for Request and Response messages whereas GRPC Kotlin expects wrapper class to be just Hello which leads to compilation errors. Simplest workaround is to rename the proto file which then results in consistent wrapper classes.

Sample project:
https://github.com/dariuszkuc/grpc-kotlin-issue

protoc-gen-grpckt: program not found or is not executable

After following the steps in the README.md file I am not able to generate the proto files from the command line

git clone [email protected]:grpc/grpc-kotlin.git
cd grpc-kotlin/
./gradlew build
vi test.proto // make some test proto file
mkdir testDir
protoc --plugin=protoc-gen-grpc-kotlin=build/artifacts/protoc-gen-grpc-kotlin --grpckt_out=testDir --proto_path=. test.proto

And the result from this is

protoc-gen-grpckt: program not found or is not executable
Please specify a program using absolute path or make sure the program is available in your PATH system variable
--grpckt_out: protoc-gen-grpckt: Plugin failed with status code 1.

protoc version - 3.11.4

First release tasks

• README:
  • Remove pre-release warning. Provide basic info. #46
  • Add download, setup and build instructions #17
• Publish API reference to gh-pages #4, #5.
• Publish to maven #10.
• Consider adding a RELEASING.md file like grpc-java #30
• Ensure that release version number matches grpc core and/or grpc-java?

cc @lowasser @dwiner @thisisnotapril - feel free to add items.

Dispatchers.IO Coroutines Example

In the context of a gRPC server. I'm wondering if we could get some guidance around, perhaps in an example, of how best to handle long-running blocking logic (e.g. blocking upstream request) using coroutine.

In particular keen to know, for example a gRPC call upstream request, is the recommended way of making way of running long-running requests using withContext(Dispatchers.IO) or is this somewhat irrelevant because the server is already optimized for coroutines. More broadly, how do the servers thread pools relate to the coroutines on the gRPC server?

    override suspend fun blockingHello(request: HelloRequest): HelloReply {
        return mockBlockingApiCall(request)
    }

    private suspend fun mockBlockingApiCall(request: HelloRequest): HelloReply = withContext(Dispatchers.IO) {
        delay(3_000) // emulate long running API call
        buildReply(toMessage(request.name))
    }

https://github.com/grpc/grpc-kotlin/blob/master/stub/src/main/java/io/grpc/kotlin/AbstractCoroutineServerImpl.kt#L32

Is it required to set `java_multiple_files = true` option in proto definition

When I try to build the project without setting java_multiple_files = true option in proto definition, I got Unresolved reference: error. It seems like the generated code referring to message type like <service-name>.<message-name> but there is no java class generated with the service-name.

When I set the java_multiple_files option to true. The code generates correctly and builds successfully.

Example on how to use gRPC context

What is the recommended way to use gRPC metadata?
I cannot see anything in the examples and want to figure out what is the safest way in terms of concurrency and backward compatibility.

stub-lite Doesn't Seem to Work

I tried using stub-lite on a project that only compiled protos but the compile failed on some imports, like:
import io.grpc.kotlin.AbstractCoroutineServerImpl

Maybe I'm using it wrong.

Setup gh-pages

The gh-pages branch will be used to publish the Kotlin gRPC API.
cc @bshaffer @lowasser @dwiner.

Generate Kotlin source for .proto messages?

Is there a way to generate Kotlin files from a proto3 message? Like Java's protoc but for Kotlin files?