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 f902373311b1bdc8782de1459decd98830d1e1bc Author: chaokunyang <[email protected]> AuthorDate: Fri Jun 12 18:35:56 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 17 ++++++---- docs/compiler/flatbuffers-idl.md | 9 ++--- docs/compiler/generated-code.md | 71 ++++++++++++++++++++++++++++++++++++++++ docs/compiler/index.md | 10 +++--- docs/compiler/protobuf-idl.md | 36 ++++++++++---------- docs/compiler/schema-idl.md | 6 ++-- 6 files changed, 112 insertions(+), 37 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index dbad7568f3..683bd3417d 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -141,23 +141,24 @@ foryc schema.fdl --output ./src/generated foryc user.fdl order.fdl product.fdl --output ./generated ``` -**Compile a simple schema containing service definitions (Java + Python + Rust models):** +**Compile a simple schema containing service definitions (Java + Python + Rust + Kotlin models):** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --kotlin_out=./generated/kotlin ``` -**Generate Java, Python, and Rust gRPC service companions:** +**Generate Java, Python, Rust, and Kotlin gRPC service companions:** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --grpc +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --kotlin_out=./generated/kotlin --grpc ``` The generated gRPC service code uses Fory to serialize request and response payloads. Java output imports grpc-java APIs, Python output imports `grpc`, and -Rust output imports `tonic` and `bytes`; applications that compile or run those -generated service files must provide their own gRPC dependencies. Fory packages -do not add a hard gRPC dependency for this feature. +Rust output imports `tonic` and `bytes`. Kotlin output imports grpc-java and +grpc-kotlin APIs and uses coroutine stubs. Applications that compile or run +those generated service files must provide their own gRPC dependencies. Fory +packages do not add a hard gRPC dependency for this feature. **Use import search paths:** @@ -443,6 +444,8 @@ generated/ - Enums use stable Fory enum IDs - Unions use sealed classes with `@ForyUnion`, `@ForyCase`, and an unknown-case carrier - Schema module object included +- With `--grpc`, one `<ServiceName>GrpcKt.kt` coroutine service companion per + service ### C# IDL Matrix Verification diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md index 45e88e10af..fa29946acb 100644 --- a/docs/compiler/flatbuffers-idl.md +++ b/docs/compiler/flatbuffers-idl.md @@ -126,7 +126,7 @@ message Container { FlatBuffers `rpc_service` definitions are translated to Fory services. With `--grpc`, the compiler emits gRPC service companions for supported outputs such -as Java, Python, Go, and Rust. These companions use Fory serialization for +as Java, Python, Go, Rust, and Kotlin. These companions use Fory serialization for request and response payloads. ```fbs @@ -137,12 +137,13 @@ rpc_service SearchService { ``` ```bash -foryc api.fbs --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --grpc +foryc api.fbs --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --kotlin_out=./generated/kotlin --grpc ``` Generated service code imports grpc APIs, so applications must provide grpc-java, -`grpcio`, grpc-go, or Rust `tonic` and `bytes` dependencies when they compile or -run those files. Fory packages do not add gRPC as a hard dependency. +grpc-kotlin, `grpcio`, grpc-go, or Rust `tonic` and `bytes` dependencies when +they compile or run those files. Fory packages do not add gRPC as a hard +dependency. ### Defaults and Metadata diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index 1764c47a14..d197fb86f0 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -1376,6 +1376,77 @@ public object AddressbookForyModule : ForyModule { `registerUnion` discovers the generated `<Target>_ForySerializer`; callers do not pass a serializer instance. +### gRPC Service Companions + +When a schema contains services and the compiler is run with `--grpc`, Kotlin +generation emits one `<ServiceName>GrpcKt.kt` file per service next to the model +types. The file contains a grpc-kotlin coroutine companion object, not Java +`*Grpc.java` source. + +```kotlin +public object AddressBookServiceGrpcKt { + public const val SERVICE_NAME: String = "addressbook.AddressBookService" + + @JvmStatic + public val serviceDescriptor: io.grpc.ServiceDescriptor + get() = serviceDescriptorValue + + @JvmStatic + public val lookupMethod: io.grpc.MethodDescriptor<Person, AddressBook> + get() = lookupMethodValue + + public abstract class AddressBookServiceCoroutineImplBase( + coroutineContext: kotlin.coroutines.CoroutineContext = + kotlin.coroutines.EmptyCoroutineContext, + ) : io.grpc.kotlin.AbstractCoroutineServerImpl(coroutineContext) { + public open suspend fun lookup(request: Person): AddressBook = + throw io.grpc.StatusException( + io.grpc.Status.UNIMPLEMENTED.withDescription( + "Method addressbook.AddressBookService/Lookup is unimplemented", + ), + ) + } + + public class AddressBookServiceCoroutineStub @JvmOverloads constructor( + channel: io.grpc.Channel, + callOptions: io.grpc.CallOptions = io.grpc.CallOptions.DEFAULT, + ) : io.grpc.kotlin.AbstractCoroutineStub<AddressBookServiceCoroutineStub>( + channel, + callOptions, + ) { + public suspend fun lookup( + request: Person, + headers: io.grpc.Metadata = io.grpc.Metadata(), + ): AddressBook = + io.grpc.kotlin.ClientCalls.unaryRpc( + channel, + lookupMethod, + request, + callOptions, + headers, + ) + } +} +``` + +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>` | + +Each method descriptor uses a Fory-backed `io.grpc.MethodDescriptor.Marshaller` +that reuses the generated schema module's `ThreadSafeFory`. Generated service +companions do not call protobuf parsers, do not expose KSP serializer class +names, and do not create Fory instances per call. + +Applications compiling the generated Kotlin service files must provide +grpc-java, grpc-kotlin, and `kotlinx-coroutines-core` dependencies. Fory Kotlin +artifacts do not add those gRPC dependencies as hard dependencies. + ## Scala The Scala target emits Scala 3 source only. The `fory-scala` artifact still diff --git a/docs/compiler/index.md b/docs/compiler/index.md index 0bcc5ba6fe..f9fea15b45 100644 --- a/docs/compiler/index.md +++ b/docs/compiler/index.md @@ -23,7 +23,7 @@ Fory IDL is a schema definition language for Apache Fory that enables type-safe cross-language serialization. Define your data structures once and generate native data structure code for Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin. Fory IDL can also -describe RPC services; for Java, Python, Go, and Rust, the compiler can +describe RPC services; for Java, Python, Go, Rust, and Kotlin, the compiler can generate gRPC service companions that use Fory serialization for request and response payloads. @@ -88,16 +88,16 @@ service AnimalService { } ``` -Generate Java, Python, and Rust models plus gRPC service companions with: +Generate Java, Python, Rust, and Kotlin models plus gRPC service companions with: ```bash -foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --grpc +foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --kotlin_out=./generated/kotlin --grpc ``` The generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. Applications provide their own grpc-java, -`grpcio`, grpc-go, or Rust `tonic` and `bytes` dependencies; Fory packages do -not add gRPC as a hard dependency. +grpc-kotlin, `grpcio`, grpc-go, or Rust `tonic` and `bytes` dependencies; Fory +packages do not add gRPC as a hard dependency. ## Why Fory IDL? diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md index 66e0e4bc1e..4ce825e37d 100644 --- a/docs/compiler/protobuf-idl.md +++ b/docs/compiler/protobuf-idl.md @@ -41,17 +41,17 @@ how protobuf concepts map to Fory, and how to use protobuf-only Fory extension o ## Protobuf vs Fory at a Glance -| Aspect | Protocol Buffers | Fory | -| ------------------ | ----------------------------- | ------------------------------------- | -| Primary purpose | RPC/message contracts | High-performance object serialization | -| Encoding model | Tag-length-value | Fory binary protocol | -| Reference tracking | Not built-in | First-class (`ref`) | -| Circular refs | Not supported | Supported | -| Unknown fields | Preserved | Not preserved | -| Generated types | Protobuf-specific model types | Native language constructs | -| gRPC ecosystem | Native | Java/Python/Go/Rust service codegen | - -Fory can generate Java, Python, Go, and Rust gRPC service companions with +| Aspect | Protocol Buffers | Fory | +| ------------------ | ----------------------------- | ------------------------------------------ | +| Primary purpose | RPC/message contracts | High-performance object serialization | +| Encoding model | Tag-length-value | Fory binary protocol | +| Reference tracking | Not built-in | First-class (`ref`) | +| Circular refs | Not supported | Supported | +| Unknown fields | Preserved | Not preserved | +| Generated types | Protobuf-specific model types | Native language constructs | +| gRPC ecosystem | Native | Java/Python/Go/Rust/Kotlin service codegen | + +Fory can generate Java, Python, Go, Rust, and Kotlin gRPC service companions with `--grpc`. Those services use normal gRPC transports but serialize request and response payloads with Fory rather than protobuf. For broad gRPC ecosystem tooling, schema reflection, and protobuf-native interceptors, protobuf remains @@ -314,16 +314,16 @@ languages. For supported service outputs, add `--grpc` to emit gRPC companion code: ```bash -foryc api.proto --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --grpc +foryc api.proto --java_out=./generated/java --python_out=./generated/python --rust_out=./generated/rust --kotlin_out=./generated/kotlin --grpc ``` Generated Java service files compile against grpc-java, generated Python service -modules import `grpc`, and generated Rust service files import `tonic` and -`bytes`. Add those dependencies in your application build; Fory packages do not -add gRPC as a hard dependency. Protobuf `oneof` fields are translated to Fory -union fields inside request and response messages. Direct union RPC request or -response types are not part of normal protobuf RPC -syntax. +modules import `grpc`, generated Rust service files import `tonic` and `bytes`, +and generated Kotlin service files compile against grpc-java and grpc-kotlin. +Add those dependencies in your application build; Fory packages do not add gRPC +as a hard dependency. Protobuf `oneof` fields are translated to Fory union +fields inside request and response messages. Direct union RPC request or +response types are not part of normal protobuf RPC syntax. ### Step 5: Run Compatibility Checks diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md index c59bbe4c6b..40f0821088 100644 --- a/docs/compiler/schema-idl.md +++ b/docs/compiler/schema-idl.md @@ -908,7 +908,7 @@ union_field := ['repeated'] field_type IDENTIFIER '=' INTEGER [field_options] '; Services define RPC method contracts in Fory IDL. They are optional: schemas with services still generate the normal data model types, and gRPC service code is generated only when the compiler is run with `--grpc` for supported language -outputs such as Java, Python, Go, and Rust. +outputs such as Java, Python, Go, Rust, and Kotlin. ```protobuf message GetPetRequest [id=200] { @@ -950,8 +950,8 @@ service PetDirectory { of a service contract. - The generated gRPC companions use Fory serialization for each RPC payload. Applications that compile or run those companions provide their own gRPC - dependency, such as grpc-java, `grpcio`, grpc-go, or Rust `tonic` and - `bytes`. + dependency, such as grpc-java, grpc-kotlin, `grpcio`, grpc-go, or Rust + `tonic` and `bytes`. **Grammar:** --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
