This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 240723c0db81e0a197c816542df0c1f0d3314789 Author: chaokunyang <[email protected]> AuthorDate: Fri Jun 12 18:35:56 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/java/grpc-support.md | 3 + docs/guide/kotlin/android-support.md | 2 +- docs/guide/kotlin/grpc-support.md | 179 +++++++++++++++++++++++++++++++++++ docs/guide/kotlin/index.md | 2 + 4 files changed, 185 insertions(+), 1 deletion(-) diff --git a/docs/guide/java/grpc-support.md b/docs/guide/java/grpc-support.md index bfa1781e3e..4a233852de 100644 --- a/docs/guide/java/grpc-support.md +++ b/docs/guide/java/grpc-support.md @@ -30,6 +30,9 @@ Fory payload encoding. Use standard protobuf gRPC code generation when your API must be consumed by generic protobuf clients, reflection tools, or components that expect protobuf message bytes. +For Kotlin coroutine stubs and service bases, see +[Kotlin gRPC Support](../kotlin/grpc-support.md). + ## Add Dependencies The generated Java service files compile against grpc-java. Fory Java artifacts diff --git a/docs/guide/kotlin/android-support.md b/docs/guide/kotlin/android-support.md index 9ecafb4f22..3f8c66b67f 100644 --- a/docs/guide/kotlin/android-support.md +++ b/docs/guide/kotlin/android-support.md @@ -1,6 +1,6 @@ --- title: Android Support -sidebar_position: 6 +sidebar_position: 7 id: android_support license: | Licensed to the Apache Software Foundation (ASF) under one or more diff --git a/docs/guide/kotlin/grpc-support.md b/docs/guide/kotlin/grpc-support.md new file mode 100644 index 0000000000..ae12f9e0f1 --- /dev/null +++ b/docs/guide/kotlin/grpc-support.md @@ -0,0 +1,179 @@ +--- +title: Kotlin gRPC Support +sidebar_position: 6 +id: grpc_support +license: | + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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. +--- + +Fory IDL can generate Kotlin coroutine gRPC companions. The generated gRPC +files use normal grpc-java and grpc-kotlin APIs, while each request and response +message is serialized with Fory. + +## Dependencies + +Add Fory Kotlin, KSP, grpc-java, grpc-kotlin, coroutines, and one grpc-java +transport to the application or service module that compiles the generated +source. + +```kotlin +plugins { + id("com.google.devtools.ksp") version "<ksp-version>" +} + +dependencies { + implementation("org.apache.fory:fory-kotlin:<fory-version>") + ksp("org.apache.fory:fory-kotlin-ksp:<fory-version>") + + implementation("io.grpc:grpc-api:<grpc-version>") + implementation("io.grpc:grpc-stub:<grpc-version>") + implementation("io.grpc:grpc-kotlin-stub:<grpc-kotlin-version>") + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:<coroutines-version>") + + runtimeOnly("io.grpc:grpc-netty-shaded:<grpc-version>") +} +``` + +Use a different grpc-java transport if your application already standardizes on +one. Generated Kotlin Fory gRPC does not require `grpc-protobuf` for payload +encoding. + +## Generate Code + +For a schema such as: + +```protobuf +package demo.greeter; + +message HelloRequest { + string name = 1; +} + +message HelloReply { + string reply = 1; +} + +service Greeter { + rpc SayHello (HelloRequest) returns (HelloReply); +} +``` + +run: + +```bash +foryc service.fdl --kotlin_out=./generated/kotlin --grpc +``` + +The compiler writes Kotlin model files, a schema module such as +`ServiceForyModule.kt`, and one service companion such as `GreeterGrpcKt.kt`. +Run KSP when compiling the generated model files so the schema serializers are +available at runtime. + +## Server + +Implement the generated coroutine base class and register it with a normal +grpc-java server. + +```kotlin +import demo.greeter.GreeterGrpcKt +import demo.greeter.HelloReply +import demo.greeter.HelloRequest +import io.grpc.ServerBuilder + +class GreeterService : GreeterGrpcKt.GreeterCoroutineImplBase() { + override suspend fun sayHello(request: HelloRequest): HelloReply = + HelloReply(reply = "Hello, ${request.name}") +} + +val server = ServerBuilder + .forPort(50051) + .addService(GreeterService()) + .build() + .start() +``` + +Unimplemented generated methods fail with gRPC `UNIMPLEMENTED`. Exceptions +thrown by your service method follow grpc-kotlin server behavior. + +## Client + +Construct the generated coroutine stub directly from a grpc-java channel. + +```kotlin +import demo.greeter.GreeterGrpcKt +import demo.greeter.HelloRequest +import io.grpc.ManagedChannelBuilder + +val channel = ManagedChannelBuilder + .forAddress("localhost", 50051) + .usePlaintext() + .build() + +val stub = GreeterGrpcKt.GreeterCoroutineStub(channel) +val reply = stub.sayHello(HelloRequest(name = "Fory")) +``` + +Channel construction, shutdown, deadlines, credentials, interceptors, load +balancing, retries, and server lifecycle stay normal grpc-java/grpc-kotlin +responsibilities. + +## Streaming + +Streaming RPCs use `kotlinx.coroutines.flow.Flow`. + +| IDL shape | Server method | Client method | +| ----------------------------------------- | ----------------------------------------- | ----------------------------------------- | +| `rpc A (Req) returns (Res)` | `suspend fun a(request: Req): Res` | `suspend fun a(request: Req): Res` | +| `rpc A (Req) returns (stream Res)` | `fun a(request: Req): Flow<Res>` | `fun a(request: Req): Flow<Res>` | +| `rpc A (stream Req) returns (Res)` | `suspend fun a(requests: Flow<Req>): Res` | `suspend fun a(requests: Flow<Req>): Res` | +| `rpc A (stream Req) returns (stream Res)` | `fun a(requests: Flow<Req>): Flow<Res>` | `fun a(requests: Flow<Req>): Flow<Res>` | + +The generated method path keeps the exact service and method names from the +schema, for example `/demo.greeter.Greeter/SayHello`. + +## Interoperability + +Generated Kotlin service companions use Fory binary payloads inside gRPC +frames. They are interoperable with other Fory gRPC companions generated from +the same schema, such as Java, Go, Python, and Rust companions. Generic +protobuf gRPC clients cannot decode these payloads. + +Direct union request and response types are supported for Fory IDL services. +For protobuf input, use the protobuf service shapes accepted by the protobuf +frontend; protobuf `oneof` fields are translated into Fory union fields inside +messages. + +## Troubleshooting + +**Generated service file is missing** + +Pass `--grpc` together with `--kotlin_out`. Schemas without service definitions +only generate model files and the schema module. + +**Serializer class not found at runtime** + +Ensure KSP runs for the generated Kotlin model sources and that +`fory-kotlin-ksp` uses the same Fory version as `fory-kotlin`. + +**gRPC classes are unresolved** + +Add grpc-java and grpc-kotlin dependencies to the application module. Fory +Kotlin artifacts do not add those dependencies automatically. + +**A protobuf client cannot read responses** + +Fory gRPC uses Fory binary protocol payloads, not protobuf wire-format messages. +Use generated Fory gRPC companions on both sides for the same service schema. diff --git a/docs/guide/kotlin/index.md b/docs/guide/kotlin/index.md index a8bc9c4315..92aeb09bb1 100644 --- a/docs/guide/kotlin/index.md +++ b/docs/guide/kotlin/index.md @@ -40,6 +40,7 @@ Fory Kotlin inherits all features from Fory Java, plus Kotlin-specific optimizat - **Default Value Support**: Automatic handling of Kotlin data class default parameters during schema evolution - **Static Xlang Serializers**: KSP-generated schema serializers for Kotlin/JVM and Android xlang mode - **Schema IDL Generation**: Fory compiler output for Kotlin models, sealed unions, and schema modules +- **Kotlin gRPC Support**: Coroutine service companions that use Fory payload serialization - **Schema Evolution**: Forward/backward compatibility for class schema changes See [Java Features](../java/index.md#features) for complete feature list. @@ -130,4 +131,5 @@ Fory Kotlin is built on top of Fory Java. Most configuration options, features, - [Schema Metadata](schema-metadata.md) - Kotlin annotations, nullability, references, and integer metadata - [Default Values](default-values.md) - Kotlin data class default values support - [Static Generated Serializers](static-generated-serializers.md) - KSP xlang/schema serializer generation +- [Kotlin gRPC Support](grpc-support.md) - Coroutine stubs and service bases for Fory IDL services - [Android Support](android-support.md) - Android setup, R8 behavior, and release-build validation --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
