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 2a00391b44a7c524f8f4ce560d660b4a067a7b13 Author: chaokunyang <[email protected]> AuthorDate: Sun Jun 21 12:54:01 2026 +0000 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/' --- docs/compiler/compiler-guide.md | 14 +++++++++----- docs/compiler/flatbuffers-idl.md | 17 +++++++++-------- docs/compiler/generated-code.md | 41 ++++++++++++++++++++++++++++++++++++++++ docs/compiler/index.md | 18 +++++++++--------- docs/compiler/protobuf-idl.md | 41 ++++++++++++++++++++-------------------- docs/compiler/schema-idl.md | 8 ++++---- 6 files changed, 93 insertions(+), 46 deletions(-) diff --git a/docs/compiler/compiler-guide.md b/docs/compiler/compiler-guide.md index 0c5ebd4912..89a2427b64 100644 --- a/docs/compiler/compiler-guide.md +++ b/docs/compiler/compiler-guide.md @@ -143,16 +143,16 @@ foryc schema.fdl --output ./src/generated foryc user.fdl order.fdl product.fdl --output ./generated ``` -**Compile a simple schema containing service definitions (Java + Python + Go + Rust + C# + Scala + Kotlin + JavaScript models):** +**Compile a simple schema containing service definitions (Java + Python + Go + Rust + C# + Dart + Scala + Kotlin + JavaScript models):** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript ``` -**Generate Java, Python, Go, Rust, C#, Scala, Kotlin, and Node.js JavaScript gRPC service companions:** +**Generate Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and Node.js JavaScript gRPC service companions:** ```bash -foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc +foryc compiler/examples/service.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` The generated gRPC service code uses Fory to serialize request and response @@ -161,7 +161,8 @@ payloads. Java output imports grpc-java APIs, Python output defaults to Scala output imports grpc-java APIs, and Kotlin output imports grpc-java and grpc-kotlin APIs and uses coroutine stubs. C# output imports `Grpc.Core.Api` types and can be hosted with normal .NET gRPC packages such as `Grpc.AspNetCore` -or called through `Grpc.Net.Client`. JavaScript output imports `@grpc/grpc-js`. +or called through `Grpc.Net.Client`. Dart output imports `package:grpc`. +JavaScript output imports `@grpc/grpc-js`. 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. @@ -440,6 +441,9 @@ generated/ - IDL module class included in the main file; generated serializer metadata is included in the part file - Typed arrays used for non-optional, non-ref primitive lists (e.g., `Int32List`) +- With `--grpc`, one `<stem>_grpc.dart` companion per schema is generated next to + the model file, containing each service's `Client` and `ServiceBase`; it + imports `package:grpc` ### Scala diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md index 89b3751531..0ad11a6487 100644 --- a/docs/compiler/flatbuffers-idl.md +++ b/docs/compiler/flatbuffers-idl.md @@ -126,8 +126,8 @@ 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, Rust, C#, Scala, Kotlin, and JavaScript. JavaScript browser -clients are generated with `--grpc-web`. These companions use Fory +as Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and JavaScript. JavaScript +browser clients are generated with `--grpc-web`. These companions use Fory serialization for request and response payloads. ```fbs @@ -138,16 +138,17 @@ rpc_service SearchService { ``` ```bash -foryc api.fbs --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc +foryc api.fbs --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` Generated service code imports grpc APIs, so applications must provide grpc-java, grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, -`@grpc/grpc-js`, or C# `Grpc.Core.Api` plus server/client dependencies when they -compile or run those files. Python companions use `grpc.aio` by default and can -be generated in sync mode with `--grpc-python-mode=sync`. Fory packages do not -add gRPC as a hard dependency. Use `--grpc-web` with JavaScript output to -generate browser clients that import `grpc-web`. +`@grpc/grpc-js`, C# `Grpc.Core.Api` plus server/client dependencies, or Dart +`package:grpc` when they compile or run those files. Python companions use +`grpc.aio` by default and can be generated in sync mode with +`--grpc-python-mode=sync`. Fory packages do not add gRPC as a hard dependency. +Use `--grpc-web` with JavaScript output to generate browser clients that import +`grpc-web`. ### Defaults and Metadata diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md index 1f52db67e3..b3e5ebc91f 100644 --- a/docs/compiler/generated-code.md +++ b/docs/compiler/generated-code.md @@ -1380,6 +1380,47 @@ void main() { } ``` +### gRPC Service Companions + +When a schema contains services and the compiler is run with `--grpc`, Dart +generation emits one `<module>_grpc.dart` file per schema next to the model +types. It targets `package:grpc`. Request and response serialization uses a Fory +runtime the companion obtains automatically and that registers the schema's +types on first use, so no manual registration is required; an application may +optionally inject a custom `Fory` via the schema module's `install(...)` before +the first call. + +All four RPC modes are generated: unary, server-streaming, client-streaming, and +bidirectional. The client class extends `Client`; the service base class extends +`Service` and self-registers each method with `$addMethod`. + +```dart +class GreeterClient extends Client { + // Single response: ResponseFuture. Streaming response: ResponseStream. + ResponseFuture<HelloReply> sayHello(HelloRequest request, {CallOptions? options}) { ... } + ResponseStream<HelloReply> sayHellos(HelloRequest request, {CallOptions? options}) { ... } + ResponseFuture<HelloReply> collectHellos(Stream<HelloRequest> request, {CallOptions? options}) { ... } + ResponseStream<HelloReply> chatHellos(Stream<HelloRequest> request, {CallOptions? options}) { ... } +} + +abstract class GreeterServiceBase extends Service { + Future<HelloReply> sayHello(ServiceCall call, HelloRequest request); + Stream<HelloReply> sayHellos(ServiceCall call, HelloRequest request); + Future<HelloReply> collectHellos(ServiceCall call, Stream<HelloRequest> request); + Stream<HelloReply> chatHellos(ServiceCall call, Stream<HelloRequest> request); +} +``` + +A single-response client method returns `ResponseFuture<R>` (client-streaming +adapts the streaming call with `.single`); a streaming-response method returns +`ResponseStream<R>`. On the server, implementations override the abstract methods, +which receive a single request as `Q` and a client-streaming request as +`Stream<Q>`, and return a `Future` for single responses or a `Stream` for +streaming responses. +Applications compiling these files must provide a `grpc` dependency; the Fory Dart +runtime does not add one. The original IDL method names are used in the gRPC wire +paths. + ## Kotlin The Kotlin target emits Kotlin source only. The compiler does not generate Java diff --git a/docs/compiler/index.md b/docs/compiler/index.md index da10b2cd16..caa69a6fc9 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, Rust, C#, Scala, Kotlin, and +describe RPC services; for Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and JavaScript, the compiler can generate gRPC service companions that use Fory serialization for request and response payloads. @@ -88,21 +88,21 @@ service AnimalService { } ``` -Generate Java, Python, Go, Rust, C#, Scala, Kotlin, and JavaScript models plus -gRPC service companions with: +Generate Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and JavaScript models +plus gRPC service companions with: ```bash -foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc +foryc animals.fdl --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` The generated service code uses normal gRPC APIs, but request and response objects are serialized with Fory. Applications provide their own grpc-java, grpc-kotlin, Scala grpc-java APIs, `grpcio`, grpc-go, Rust `tonic` and `bytes`, -or C# `Grpc.Core.Api` and hosting/client dependencies; Fory packages do not add -gRPC as a hard dependency. Python companions use `grpc.aio` by default and can -be generated in sync mode with `--grpc-python-mode=sync`. JavaScript Node.js -companions use `@grpc/grpc-js`; browser clients are generated separately with -`--grpc-web` and use `grpc-web`. +C# `Grpc.Core.Api` and hosting/client dependencies, or Dart `package:grpc`; Fory +packages do not add gRPC as a hard dependency. Python companions use `grpc.aio` +by default and can be generated in sync mode with `--grpc-python-mode=sync`. +JavaScript Node.js companions use `@grpc/grpc-js`; browser clients are generated +separately with `--grpc-web` and use `grpc-web`. ## Why Fory IDL? diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md index da5deba311..d9355deece 100644 --- a/docs/compiler/protobuf-idl.md +++ b/docs/compiler/protobuf-idl.md @@ -41,19 +41,19 @@ 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/C#/Scala/Kotlin/JavaScript service codegen | - -Fory can generate Java, Python, Go, Rust, C#, Scala, Kotlin, and JavaScript gRPC -service companions with `--grpc`. JavaScript browser clients are generated with -`--grpc-web`. Those services use normal gRPC transports but serialize request +| 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/C#/Dart/Scala/Kotlin/JavaScript service codegen | + +Fory can generate Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and +JavaScript gRPC service companions with `--grpc`. JavaScript browser clients are +generated with `--grpc-web`. 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 the mature/default choice. @@ -315,19 +315,20 @@ languages. For supported service outputs, add `--grpc` to emit gRPC companion code: ```bash -foryc api.proto --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc +foryc api.proto --java_out=./generated/java --python_out=./generated/python --go_out=./generated/go --rust_out=./generated/rust --csharp_out=./generated/csharp --dart_out=./generated/dart --scala_out=./generated/scala --kotlin_out=./generated/kotlin --javascript_out=./generated/javascript --grpc ``` Generated Java service files compile against grpc-java, generated Python service modules use `grpc.aio` by default, generated Rust service files import `tonic` and `bytes`, generated Go service files import grpc-go, generated JavaScript Node.js service files import `@grpc/grpc-js`, generated C# service files import -`Grpc.Core.Api` types, generated Scala service files compile against grpc-java, -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. Use `--grpc-python-mode=sync` for sync Python `grpcio` -companions. Use `--grpc-web` with JavaScript output to generate browser clients -that import `grpc-web`. +`Grpc.Core.Api` types, generated Dart service files import `package:grpc`, +generated Scala service files compile against grpc-java, 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. +Use `--grpc-python-mode=sync` for sync Python `grpcio` companions. Use +`--grpc-web` with JavaScript output to generate browser clients that import +`grpc-web`. 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. diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md index d2e12c989e..633b90f1e0 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, Rust, C#, Scala, Kotlin, and JavaScript. +outputs such as Java, Python, Go, Rust, C#, Dart, Scala, Kotlin, and JavaScript. JavaScript browser gRPC-Web clients are generated with `--grpc-web`. ```protobuf @@ -952,9 +952,9 @@ service PetDirectory { - 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, grpc-kotlin, `grpcio`, grpc-go, Rust `tonic` - and `bytes`, Scala grpc-java APIs, `@grpc/grpc-js`, `grpc-web`, or C# - `Grpc.Core.Api` plus a server or client package. Python companions use - `grpc.aio` by default and can be generated in sync mode with + and `bytes`, Scala grpc-java APIs, `@grpc/grpc-js`, `grpc-web`, C# + `Grpc.Core.Api` plus a server or client package, or Dart `package:grpc`. Python + companions use `grpc.aio` by default and can be generated in sync mode with `--grpc-python-mode=sync`. **Grammar:** --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
