From 97b3e0e88efe60c894f565d3cc8397f50cdc555d Mon Sep 17 00:00:00 2001 From: Alexander Sysoev Date: Fri, 17 Jan 2025 17:14:32 +0100 Subject: [PATCH 1/3] Added docs for the gRPC --- README.md | 14 ++- docs/pages/kotlinx-rpc/rpc.tree | 6 + .../kotlinx-rpc/topics/grpc-client.topic | 26 +++++ .../topics/grpc-configuration.topic | 107 ++++++++++++++++++ .../kotlinx-rpc/topics/grpc-server.topic | 19 ++++ .../kotlinx-rpc/topics/grpc-services.topic | 102 +++++++++++++++++ 6 files changed, 271 insertions(+), 3 deletions(-) create mode 100644 docs/pages/kotlinx-rpc/topics/grpc-client.topic create mode 100644 docs/pages/kotlinx-rpc/topics/grpc-configuration.topic create mode 100644 docs/pages/kotlinx-rpc/topics/grpc-server.topic create mode 100644 docs/pages/kotlinx-rpc/topics/grpc-services.topic diff --git a/README.md b/README.md index ad7a96be6..fd8531ef2 100644 --- a/README.md +++ b/README.md @@ -156,9 +156,17 @@ When using kRPC you only need to provide a transport or choose from the official 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](https://grpc.io/) (in prototype) +`kotlinx.rpc` aims to provide most common protocols integrations as well as the in-house one called kRPC. + +## gRPC integration +Library provides experimental support for the [gRPC](https://grop.io) protocol. +The artifacts are published separately in our [Space repository](https://public.jetbrains.space/p/krpc/packages/maven/grpc) +Current latest version: + +![Dynamic XML Badge](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fmaven.pkg.jetbrains.space%2Fpublic%2Fp%2Fkrpc%2Fgrpc%2Forg%2Fjetbrains%2Fkotlinx%2Fkotlinx-rpc-core%2Fmaven-metadata.xml&query=%2F%2Fmetadata%2Fversioning%2Flatest&label=Latest%20dev%20version&color=forest-green&cacheSeconds=60) + +See more on gRPC usage in the [docs](https://kotlin.github.io/kotlinx-rpc/grpc-configuration.html). +See also [sample gRPC project](/samples/grpc-app). ## Kotlin compatibility We support all stable Kotlin versions starting from 2.0.0: diff --git a/docs/pages/kotlinx-rpc/rpc.tree b/docs/pages/kotlinx-rpc/rpc.tree index 0d5f9bc64..e671d020f 100644 --- a/docs/pages/kotlinx-rpc/rpc.tree +++ b/docs/pages/kotlinx-rpc/rpc.tree @@ -25,6 +25,12 @@ + + + + + + diff --git a/docs/pages/kotlinx-rpc/topics/grpc-client.topic b/docs/pages/kotlinx-rpc/topics/grpc-client.topic new file mode 100644 index 000000000..03d1cc188 --- /dev/null +++ b/docs/pages/kotlinx-rpc/topics/grpc-client.topic @@ -0,0 +1,26 @@ + + + + +

+ Example of using a gRPC client: +

+ + val grpcClient = GrpcClient("localhost", 8080) { + usePlaintext() + } + + val recognizer = grpcClient.withService<ImageRecognizer>() + + val image = Image { + data = byteArrayOf(0, 1, 2, 3) + } + val result = recognizer.recognize(image) + println("Recognized category: ${result.category}") + + grpcClient.cancel() + + \ No newline at end of file diff --git a/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic b/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic new file mode 100644 index 000000000..69f0ee905 --- /dev/null +++ b/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic @@ -0,0 +1,107 @@ + + + + + +

+ Artifacts for gRPC integration are published separately + and updated frequently not in sync with main releases. +

+

+ + Latest dev version + +

+ + +

+ gRPC integration is available in an experimental state. + The artifacts are published separately in our Space repository. + Current latest version can be seen in the badge on top of the page. +

+ +

Below is an example of a project setup.

+ settings.gradle.kts: + + pluginManagement { + repositories { + gradlePluginPortal() + mavenCentral() + maven("https://maven.pkg.jetbrains.space/public/p/krpc/grpc") + } + } + +

+ build.gradle.kts: +

+ + plugins { + kotlin("jvm") version "2.1.0" + kotlin("plugin.serialization") version "2.1.0" + id("org.jetbrains.kotlinx.rpc.plugin") version "<version>" + id("com.google.protobuf") version "0.9.4" + } + + repositories { + mavenCentral() + maven("https://maven.pkg.jetbrains.space/public/p/krpc/grpc") + } + + dependencies { + implementation("org.jetbrains.kotlinx:kotlinx-rpc-grpc-core:<version>") + implementation("ch.qos.logback:logback-classic:1.5.16") + implementation("io.grpc:grpc-netty:1.69.0") + } + +

Here <version> comes from the badge above.

+ + The setup has only been tested on Kotlin/JVM projects. + + + +

+ gRPC requires additional code generation from the protoc + compiler. + This can be setup up in the following way: +

+ + protobuf { + protoc { + artifact = "com.google.protobuf:protoc:4.29.3" + } + + plugins { + create("kotlinx-rpc") { + artifact = "org.jetbrains.kotlinx:kotlinx-rpc-protobuf-plugin:<version>:all@jar" + } + + create("grpc") { + artifact = "io.grpc:protoc-gen-grpc-java:1.69.0" + } + + create("grpckt") { + artifact = "io.grpc:protoc-gen-grpc-kotlin:1.4.1:jdk8@jar" + } + } + + generateProtoTasks { + all().all { + plugins { + create("kotlinx-rpc") { + option("debugOutput=protobuf-plugin.log") + option("messageMode=interface") + } + create("grpc") + create("grpckt") + } + } + } + } + + + diff --git a/docs/pages/kotlinx-rpc/topics/grpc-server.topic b/docs/pages/kotlinx-rpc/topics/grpc-server.topic new file mode 100644 index 000000000..f3b1fa5c9 --- /dev/null +++ b/docs/pages/kotlinx-rpc/topics/grpc-server.topic @@ -0,0 +1,19 @@ + + + + +

+ Example of using a gRPC server: +

+ + val grpcServer = GrpcServer(8080) { + registerService<ImageRecognizer> { ImageRecognizerImpl() } + } + + grpcServer.start() + grpcServer.awaitTermination() + + diff --git a/docs/pages/kotlinx-rpc/topics/grpc-services.topic b/docs/pages/kotlinx-rpc/topics/grpc-services.topic new file mode 100644 index 000000000..aac07cf38 --- /dev/null +++ b/docs/pages/kotlinx-rpc/topics/grpc-services.topic @@ -0,0 +1,102 @@ + + + + +

+ Define a service in the proto folder next to your source sets: +

+ + ├── build.gradle.kts + ├── settings.gradle.kts + └── src + ├── main + │ ├── kotlin + │ │ ├── Client.kt + │ │ ├── ImageRecognizer.kt + │ │ └── Server.kt + │ └── resources + │ └── logback.xml + └── proto + └── image-recognizer.proto + + +

+ Inside the file define a service: +

+ + syntax = "proto3"; + + message Image { + bytes data = 1; + } + + message RecogniseResult { + int32 category = 1; + } + + service ImageRecognizer { + rpc recognize(Image) returns (RecogniseResult); + } + +

+ Some code will be generated. The most important ones are interface ImageRecognizer, + interface Image and interface RecogniseResult: +

+ + @Grpc + interface ImageRecognizer { + suspend fun recognize(image: Image): RecogniseResult + } + + interface RecogniseResult { + val category: Int + + companion object + } + + interface Image { + val data: ByteArray + + companion object + } + +

+ You can implement the ImageRecognizer: +

+ + class ImageRecognizerImpl : ImageRecognizer { + override suspend fun recognize(image: Image): RecogniseResult { + val byte = image.data[0].toInt() + delay(100) // heavy processing + val result = RecogniseResult { + category = if (byte == 0) 0 else 1 + } + return result + } + } + +

+ Here you can also see the usage of interface RecogniseResult. + To create an instance simple use its invoke extension function: +

+ + RecogniseResult { + category = 0 + } + + + + Current known limitations: + +
  • No streaming
    • +
  • Only primitive types in messages
    • +
  • Mandatory java and kotlin protoc generation in addition to our codegen
    • +
  • Kotlin/JVM project only
    • +     + If you encounter other unexpected limitations or bugs, + please report them +     +     From 551630cdf4ec581ac9c499b757fa6ffea2bc2f9d Mon Sep 17 00:00:00 2001 From: Alexander Sysoev Date: Fri, 17 Jan 2025 20:09:04 +0100 Subject: [PATCH 2/3] update writerside version --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8a3e63011..e933ca248 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -14,7 +14,7 @@ permissions: env: INSTANCE: 'kotlinx-rpc/rpc' ARTIFACT: 'webHelpRPC2-all.zip' - DOCKER_VERSION: '241.15989' + DOCKER_VERSION: '243.22562' ALGOLIA_ARTIFACT: 'algolia-indexes-RPC.zip' ALGOLIA_APP_NAME: 'MMA5Z3JT91' ALGOLIA_INDEX_NAME: 'prod_kotlin_rpc' From 2e15319ca25fa60e198acc9a49f9f7161e7a841e Mon Sep 17 00:00:00 2001 From: Alexander Sysoev Date: Tue, 21 Jan 2025 13:09:18 +0100 Subject: [PATCH 3/3] GH comments --- README.md | 11 +++---- .../kotlinx-rpc/topics/grpc-client.topic | 5 ++++ .../topics/grpc-configuration.topic | 29 +++++++++++++++++-- .../kotlinx-rpc/topics/grpc-server.topic | 10 +++++++ .../kotlinx-rpc/topics/grpc-services.topic | 24 ++++++++------- 5 files changed, 60 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index fd8531ef2..eafc64d71 100644 --- a/README.md +++ b/README.md @@ -156,17 +156,18 @@ When using kRPC you only need to provide a transport or choose from the official 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. +`kotlinx.rpc` aims to provide support for the most common protocol integrations, as well as the in-house protocol called kRPC. ## gRPC integration -Library provides experimental support for the [gRPC](https://grop.io) protocol. -The artifacts are published separately in our [Space repository](https://public.jetbrains.space/p/krpc/packages/maven/grpc) +The library provides experimental support for the [gRPC](https://grop.io) protocol. +The artifacts are published separately in our [Space repository](https://public.jetbrains.space/p/krpc/packages/maven/grpc). Current latest version: ![Dynamic XML Badge](https://img.shields.io/badge/dynamic/xml?url=https%3A%2F%2Fmaven.pkg.jetbrains.space%2Fpublic%2Fp%2Fkrpc%2Fgrpc%2Forg%2Fjetbrains%2Fkotlinx%2Fkotlinx-rpc-core%2Fmaven-metadata.xml&query=%2F%2Fmetadata%2Fversioning%2Flatest&label=Latest%20dev%20version&color=forest-green&cacheSeconds=60) -See more on gRPC usage in the [docs](https://kotlin.github.io/kotlinx-rpc/grpc-configuration.html). -See also [sample gRPC project](/samples/grpc-app). +For more information on gRPC usage, +see the [official documentation](https://kotlin.github.io/kotlinx-rpc/grpc-configuration.html). +For a working example, see the [sample gRPC project](/samples/grpc-app). ## Kotlin compatibility We support all stable Kotlin versions starting from 2.0.0: diff --git a/docs/pages/kotlinx-rpc/topics/grpc-client.topic b/docs/pages/kotlinx-rpc/topics/grpc-client.topic index 03d1cc188..58cdc6676 100644 --- a/docs/pages/kotlinx-rpc/topics/grpc-client.topic +++ b/docs/pages/kotlinx-rpc/topics/grpc-client.topic @@ -23,4 +23,9 @@ grpcClient.cancel() + +
  • + usePlaintext() - is a JVM binding to Java gRPC runtime. Other bindings are also present. +
    • +     \ No newline at end of file diff --git a/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic b/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic index 69f0ee905..5ac509320 100644 --- a/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic +++ b/docs/pages/kotlinx-rpc/topics/grpc-configuration.topic @@ -7,8 +7,8 @@

    - Artifacts for gRPC integration are published separately - and updated frequently not in sync with main releases. + Artifacts for gRPC integration are published separately + and updated frequently, independent of the main releases.

    @@ -22,7 +22,6 @@ gRPC integration is available in an experimental state. The artifacts are published separately in our Space repository. - Current latest version can be seen in the badge on top of the page.

    Below is an example of a project setup.

    @@ -103,5 +102,29 @@ } } + +
  • + Four source sets will be generated: + +
  • java - protobuf Java declarations
    • +
  • grpc - gRPC Java declarations
    • +
  • grpckt - gRPC Kotlin wrappers for Java
    • +
  • kotlinx-rpc - pur wrappers for all of the above
    • +     +

    + You won't need to use the first three directly, only the declarations from the kotlinx-rpc + source set are intended to be used. +

    + Source sets are generated into $BUILD_DIR/generated/source/proto/main directory + unless specified otherwise. + +
  • + option("debugOutput=protobuf-plugin.log") lets you specify the file + for the protoc plugin debug output. +
    • +
  • + option("messageMode=interface") is intended to be like so. Don't change it. +
    • +     diff --git a/docs/pages/kotlinx-rpc/topics/grpc-server.topic b/docs/pages/kotlinx-rpc/topics/grpc-server.topic index f3b1fa5c9..25b8916b3 100644 --- a/docs/pages/kotlinx-rpc/topics/grpc-server.topic +++ b/docs/pages/kotlinx-rpc/topics/grpc-server.topic @@ -16,4 +16,14 @@ grpcServer.start() grpcServer.awaitTermination() + +
  • + GrpcServer allows to register multiple services, like regular RpcServer. + However, CoroutineContext parameter is not needed and should not be used. +
    • +
  • + GrpcServer does not bind to Java gRPC Server, + but provides some functions to cover for that. +
    • +     diff --git a/docs/pages/kotlinx-rpc/topics/grpc-services.topic b/docs/pages/kotlinx-rpc/topics/grpc-services.topic index aac07cf38..469df5338 100644 --- a/docs/pages/kotlinx-rpc/topics/grpc-services.topic +++ b/docs/pages/kotlinx-rpc/topics/grpc-services.topic @@ -6,7 +6,7 @@ title="Services" id="grpc-services">

    - Define a service in the proto folder next to your source sets: + To define a service, create a new .proto file in the proto folder next to your source sets:

    ├── build.gradle.kts @@ -24,7 +24,7 @@

    - Inside the file define a service: + Inside the .proto file define your service:

    syntax = "proto3"; @@ -42,8 +42,8 @@ }

    - Some code will be generated. The most important ones are interface ImageRecognizer, - interface Image and interface RecogniseResult: + This will generate the necessary code, including the most important interfaces: + ImageRecognizer, Image, RecogniseResult:

    @Grpc @@ -79,8 +79,8 @@ }

    - Here you can also see the usage of interface RecogniseResult. - To create an instance simple use its invoke extension function: + Here you can also see the usage of the RecogniseResult interface. + To create an instance, use its .invoke() extension function:

    RecogniseResult { @@ -88,15 +88,17 @@ } - - Current known limitations: + +

    Current known limitations:

  • No streaming
  • Only primitive types in messages
  • Mandatory java and kotlin protoc generation in addition to our codegen
  • Kotlin/JVM project only
    •  - If you encounter other unexpected limitations or bugs, - please report them -     +

    + If you encounter other unexpected limitations or bugs, + please report them +

    +